Manejo de errores, límite de frecuencia y administración de cuotas

Cuando consultes la API de Developer Knowledge o el servidor de MCP de Developer Knowledge en aplicaciones de producción y agentes de IA, debe haber un manejo de errores y una administración de cuotas para lograr un alto rendimiento.

En esta guía, aprenderás a hacer lo siguiente:

  • Implementa una retirada exponencial truncada con jitter para las respuestas HTTP 429.
  • Controla los códigos de error canónicos de gRPC (INVALID_ARGUMENT, PERMISSION_DENIED, RESOURCE_EXHAUSTED).
  • Administra los tiempos de espera de conexión de MCP y la lógica de reintento.
  • Aplica las prácticas recomendadas de administración de cuotas y almacenamiento en caché.

Límite de frecuencia HTTP 429 y retirada exponencial

Cuando las tasas de solicitudes superan la cuota predeterminada de la API, el servicio devuelve un error HTTP 429 Too Many Requests. Las aplicaciones deben implementar la lógica de reintento con retirada exponencial truncada y jitter para evitar sobrecargar el servicio.

Retirada exponencial truncada

Calcula las demoras de reintento con la siguiente fórmula:

retry_delay = min(max_delay, initial_delay * (2 ^ attempt) + jitter)

Usa los siguientes parámetros para calcular las demoras de reintento:

  • initial_delay: Es la demora inicial del reintento (por ejemplo, 1.0 s).
  • max_delay: Es el límite máximo de retirada (por ejemplo, 32.0 segundos).
  • attempt: Es el recuento actual de reintentos (0, 1, 2, …).
  • jitter: Valor aleatorio entre 0 y 1.0 segundos para evitar picos de sincronización de subprocesos (problema de rebaño atronador).

Manejo de errores de gRPC

Las aplicaciones que acceden al servicio a través de gRPC deben inspeccionar los valores canónicos de grpc.StatusCode.

Códigos de estado de gRPC estándar

En la siguiente tabla, se enumeran los códigos de estado canónicos de gRPC que devuelve el servicio y el control del cliente recomendado:

Código de estado de gRPC Estado de HTTP Causa principal Acción recomendada
INVALID_ARGUMENT 400 Bad Request La cadena de consulta tiene un formato incorrecto, el formato del parámetro no es válido o la máscara de campo no es válida. No volver a intentar Corrige los parámetros de la solicitud antes de repetirla.
UNAUTHENTICATED 401 Unauthorized Falta la clave de API o el token de portador de OAuth, vencieron o tienen un formato incorrecto. No volver a intentar Actualiza las credenciales o genera una clave de API válida.
PERMISSION_DENIED 403 Forbidden La clave de API no tiene permiso o la API de Developer Knowledge está inhabilitada en el proyecto. No volver a intentar Verifica que la API esté habilitada en la consola de Google Cloud.
NOT_FOUND 404 Not Found No existe la ruta de acceso al documento parent especificada. BatchGetDocuments falla de forma atómica si no se encuentra ningún documento solicitado. No volver a intentar Verifica el nombre del recurso del documento.
RESOURCE_EXHAUSTED 429 Too Many Requests Se superó el límite de frecuencia o el límite de cuota del proyecto. Vuelve a intentarlo con una retirada exponencial con jitter.
UNAVAILABLE 503 Service Unavailable Se desconectó la red de forma transitoria o se reinició el servidor. Vuelve a intentarlo con una retirada exponencial.
DEADLINE_EXCEEDED 504 Gateway Timeout La solicitud excedió el plazo de RPC configurado antes de completarse. Vuelve a intentarlo con un tiempo de espera de RPC del cliente mayor.

Administración de errores y tiempo de espera de la conexión de MCP

El servidor de MCP de Developer Knowledge es un servicio remoto alojado en https://developerknowledge.googleapis.com/mcp al que se accede a través de HTTPS (con HTTP POST o eventos enviados por el servidor). Los hosts y agentes de IA deben administrar los tiempos de espera de conexión y los errores de herramientas de forma correcta.

Tiempos de espera de ejecución de herramientas

Cuando un agente invoca search_documents, get_documents o answer_query, las llamadas a herramientas pueden exceder los períodos de tiempo de espera (por ejemplo, 30 segundos) si las conexiones de red se retrasan.

Para controlar los tiempos de espera de ejecución de herramientas, haz lo siguiente:

  • Configura los tiempos de espera del cliente: Establece los tiempos de espera de ejecución de la herramienta en 30 a 60 segundos en la configuración del cliente host de MCP.
  • Controla las interrupciones de red: Reintenta las solicitudes HTTP fallidas con una retirada exponencial cuando se produzcan interrupciones transitorias de la red o respuestas HTTP 503.
  • Inspecciona los mensajes de error: Analiza los mensajes de error estándar de JSON-RPC o los códigos de estado de error HTTP para distinguir los argumentos no válidos del agotamiento de la cuota.

Prácticas recomendadas para la administración de cuotas

Sigue estas prácticas recomendadas para mantener un uso óptimo de la API y evitar límites de frecuencia inesperados:

  1. Almacena en caché el contenido del documento recuperado: Almacena los documentos de Markdown recuperados de forma local o en una caché (como Redis) cuando compiles aplicaciones que accedan a las mismas páginas con frecuencia.
  2. Usa la recuperación por lotes: Usa documents.batchGet en lugar de ejecutar varias solicitudes documents.get secuenciales.
  3. Optimiza los campos de la consulta: Solicita solo los campos de respuesta necesarios con máscaras de campos selectivas (fields=results(parent,content)).
  4. Supervisa el consumo de cuota: Haz un seguimiento de las tasas de solicitudes a la API en el panel de la API de la consola de Google Cloud.

Contenido relacionado