Errores y límites de frecuencia

Cada endpoint falla de la misma manera, por lo que un cliente maneja errores, límites de tasa y reintentos una vez y reutiliza ese código en todas partes, incluso sobre MCP.

Toda respuesta que no sea 2xx es un objeto JSON:

{
  "defined": false,
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many requests",
  "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 }
}

• code es el error a nivel HTTP, por ejemplo UNAUTHORIZED, FORBIDDEN, NOT_FOUND, BAD_REQUEST o TOO_MANY_REQUESTS.
• data.reason, cuando está presente, es una razón más precisa legible por máquina, como auth.key_not_found o rate_limit.exceeded. Haz branching sobre ella en lugar de sobre message, que es para personas y puede cambiar.
• defined es true cuando la operación lista ese error en la referencia de la API, y false para errores que cualquier solicitud puede encontrar (autenticación, límites de tasa, una ruta desconocida).
• Un fallo de validación responde BAD_REQUEST con los problemas en data.formErrors y data.fieldErrors.

Toda respuesta también lleva un X-Request-ID. Cítalo cuando contactes con soporte, y podremos encontrar esa solicitud exacta.

Cada respuesta indica el límite contra el que se contó, en dos formas:

• los encabezados X-RateLimit-*;
• los campos estructurados IETF RateLimit (estado en vivo: r son las solicitudes restantes, t los segundos hasta que se reinicie la ventana) y RateLimit-Policy (la cuota: q es el límite, w la ventana en segundos).

Un 429 también lleva Retry-After en segundos y data.retryAfterMs. Espera al menos ese tiempo antes de la siguiente solicitud; reintentar antes se cuenta y se rechaza de nuevo.

Una operación de escritura que lista un encabezado Idempotency-Key en la referencia de la API se puede reintentar sin realizar el trabajo dos veces. Envía una clave por cada escritura lógica y repite la misma clave en cada reintento:

• la misma clave con el mismo cuerpo en un plazo de 24 horas reproduce la respuesta almacenada;
• la misma clave con un cuerpo diferente se rechaza con 422;
• un duplicado que llega mientras la primera aún se está ejecutando recibe 409.

Una operación sin el encabezado no es idempotente, así que reinténtala solo cuando sepas que el primer intento no se completó.