Códigos de error de la API
Cada fallo de la API pública es un documento de problema RFC 9457. Su miembro code es estable y no se traduce, así que reacciona al código y no al texto legible de detail.
El documento de problema
Las respuestas usan el tipo de contenido application/problem+json y llevan type, title, status, code y detail. El miembro type enlaza de vuelta a esta página, anclado en el código. El miembro detail indica el motivo concreto por el que se rechazó la llamada —un plan sin asientos libres, un id de rol desconocido—, así que es lo que hay que leer para decidir el siguiente paso, mientras que code sigue siendo aquello sobre lo que ramificar. Cuando el edge proporciona un ray id se devuelve como requestId, que es el valor que conviene citar en una consulta de soporte, y los fallos de validación añaden un array errors con una entrada por cada valor rechazado.
Códigos
El estado HTTP se deriva del código, así que un cliente puede basarse en cualquiera de los dos. Trata un código desconocido como un error del servidor.
| Código | Estado HTTP | Significado |
|---|---|---|
| INPUT_PARSE_ERROR | 400 | El cuerpo, la consulta o los parámetros de ruta no pasaron la validación del esquema. El array errors localiza cada valor rechazado y nombra la restricción que incumplió. |
| BAD_REQUEST | 400 | La petición se entendió pero no es válida en este contexto. |
| NOT_AUTHORIZED | 401 | No se presentó ninguna credencial, o está malformada, caducada o revocada. La cabecera WWW-Authenticate apunta a los metadatos del recurso que un cliente OAuth necesita para iniciar la conexión. |
| FORBIDDEN | 403 | La credencial es válida pero le falta el permiso necesario, es una clave de equipo usada fuera de su propio equipo o en una operación de la cuenta, su propietario no tiene el permiso de equipo que requiere esta operación, o lo impide un límite del plan como el número de asientos del equipo. El miembro detail indica cuál. |
| NOT_FOUND | 404 | El recurso indicado no existe o no es visible para esta credencial. |
| CONFLICT | 409 | La petición entra en conflicto con el estado actual del recurso. |
| PRECONDITION_FAILED | 409 | No se cumplió una regla de la operación: por ejemplo un límite del plan o una invitación ya utilizada. |
| RATE_LIMITED | 429 | Demasiadas peticiones para esta credencial o dirección IP. Las credenciales autenticadas permiten 300 peticiones por cada 60 segundos; los intentos de autenticación fallidos usan un límite por IP independiente. Espera los segundos indicados en retry-after. |
| INTERNAL_SERVER_ERROR | 500 | Algo falló en el servidor. Los detalles se omiten a propósito; reintenta y cita requestId si el problema persiste. |
Errores de campo
Un INPUT_PARSE_ERROR incluye un array errors con una entrada por cada valor rechazado. Cada entrada localiza el valor e indica qué falló: in dice de qué parte de la petición procede, con el mismo vocabulario que un parámetro de OpenAPI (body, query, path, header, cookie); pointer es un JSON Pointer según RFC 6901, de modo que /scopes/1 direcciona el segundo elemento y una cadena vacía direcciona todo el cuerpo; code es un identificador estable y sin traducir de la tabla siguiente; y params incluye la restricción incumplida, como {"min": 2}, cuando el código tiene alguna. Los códigos describen la forma del fallo y no el texto mostrado al usuario, así que es seguro ramificar sobre ellos.
| Código | Significado |
|---|---|
| required | Falta el valor. Envía el miembro, o no realices la petición hasta que puedas. |
| invalid_type | El valor es de un tipo incorrecto. params.expected indica el tipo de JSON Schema que documenta la operación. |
| invalid_value | El valor es del tipo correcto pero no es uno que la operación acepte: un valor fuera de una enumeración, o rechazado por una regla propia de esta operación. El documento OpenAPI enumera los valores permitidos. |
| invalid_format | El valor no cumple el formato que exige el miembro. params.format lo indica, por ejemplo email. |
| min_length | La cadena o el array es más corto de lo permitido. params.min es el mínimo. |
| max_length | La cadena o el array es más largo de lo permitido. params.max es el máximo. |
| min_value | El número está por debajo del rango permitido. params.min es el mínimo. |
| max_value | El número está por encima del rango permitido. params.max es el máximo. |
Reintentar con seguridad
Vale la pena reintentar las respuestas 429 y 5xx con backoff, respetando retry-after cuando está presente. Mejor aún, ajusta el ritmo con RateLimit-Remaining y RateLimit-Reset, que vienen en todas las respuestas, y reduce la frecuencia antes de alcanzar el límite. Los demás códigos 4xx volverán a fallar igual y necesitan otra petición, otra credencial o un permiso que la credencial todavía no tiene.