Códigos de error

Todo error de la API tiene un código error estable. Ramifica según error para un manejo preciso, ramifica según type para cubos gruesos y registra siempre request_id cuando esté presente para que el equipo de soporte pueda rastrear la llamada.

Sobres de error

Los endpoints del protocolo OAuth siguen errores al estilo de RFC 6749:

{
 "error": "invalid_request",
 "error_description": "code_challenge_method is required and must be S256"
}

Los errores de la API de datos para desarrolladores mantienen el mismo campo plano error y pueden añadir un type grueso más un request_id rastreable:

{
 "error": "insufficient_scope",
 "scope": "recipe:publish",
 "type": "auth_error",
 "request_id": "req_..."
}

La validación de esquema se ejecuta antes que cualquier handler. Un cuerpo o formulario que no cumple el esquema OpenAPI se responde con validation_error y un array details que nombra cada campo problemático; este sobre no lleva type, error_description ni request_id, y el código que habría devuelto el handler nunca llega a aparecer: un grant_type desconocido en POST /oauth/token sale como validation_error, no como unsupported_grant_type, y un POST /oauth/register sin redirect_uris como validation_error, no como invalid_request.

{
 "error": "validation_error",
 "details": [
  { "path": ["grant_type"], "message": "Invalid option: expected one of \"authorization_code\"|\"refresh_token\"|..." }
 ]
}

Las respuestas de límite de tasa incluyen tiempos de reintento accionables por máquina:

{
 "error": "rate_limited",
 "retry_after_ms": 1200,
 "next_request_at": "2026-06-17T12:00:01Z",
 "hint": "Rate limited. Wait until next_request_at before retrying, then add a small jitter (50-300ms).",
 "agent_instruction": "sleep_until_next_request_at"
}

Tipos de error

Códigos comunes

La columna Tipo es el campo type que la respuesta lleva de verdad. Los cuerpos del protocolo OAuth (OAuthProtocolError) y los previos al handler (validation_error, unauthorized) no lo tienen, así que sus filas muestran un guion.

Encabezados que conviene registrar

Manuales de diagnóstico

invalid_token

Comprueba que el encabezado sea exactamente Authorization: Bearer <access_token>. Si el token caducó o fue revocado, refréscalo o vuelve a pasar al usuario por el consentimiento. Mantén separadas las credenciales de prueba y las activas; un cliente de prueba devuelve datos del sandbox.

insufficient_scope

Lee el campo scope del cuerpo de error. Solicita ese ámbito para el cliente, obtén un consentimiento nuevo y reintenta con el nuevo token.

invalid_request de PKCE

PKCE es obligatorio y solo con S256. Incluye code_challenge, pon code_challenge_method en S256 y nunca uses plain.

rate_limited

Espera hasta next_request_at o hasta el encabezado Retry-After y luego reintenta con un poco de jitter. No hagas sondeo en un bucle cerrado.

quota_exceeded

La cuota de publicación es independiente de los límites de tasa de lectura. Las degradaciones suaves incluyen X-Quota-Restored-At; las degradaciones duras no se restauran automáticamente y requieren cambios de comportamiento o revisión.

Errores de idempotencia

Usa una Idempotency-Key por operación lógica de publicación. Reutilizar la misma clave con el mismo cuerpo reproduce el resultado sin riesgo; reutilizarla con un cuerpo distinto devuelve idempotency_key_reuse.

validation_error

La petición nunca llegó al handler: lee details[].path, corrige cada campo según el esquema OpenAPI y reintenta. Solo un cuerpo que valida puede producir los códigos propios del endpoint (unsupported_grant_type, invalid_scope, invalid_redirect_uri, …): cuerpos RFC 6749 con error más un error_description opcional, también sin type ni request_id.

Relacionado

• Primitivas de consistencia — el sobre de error, la paginación, la idempotencia y las convenciones de límite de tasa
• Explorador de API — mira estos cuerpos y encabezados en vivo
• Descripción general de la API — la superficie de endpoints y los enlaces a OpenAPI