Errores
Toda respuesta de error tiene el mismo cuerpo:
{
"error": {
"codigo": "SCOPE_REQUIRED",
"mensaje": "La clave no tiene el permiso que pide esta operación.",
"id_peticion": "00000000-0000-4000-8000-000000000001"
}
}codigoes estable: compara contra él.mensajees una explicación en español para personas. Puede cambiar; no lo uses para decidir nada.id_peticioncoincide con la cabeceraX-Request-ID, que llevan todas las respuestas, también las correctas. Cítalo al escribir a soporte.
Códigos
Los códigos son los del enum de ErrorDetails.codigo del OpenAPI; el estado y la descripción salen de las
respuestas que los citan.
| Código | Estado | Cuándo |
|---|---|---|
INVALID_API_KEY | 401 | Clave ausente, mal formada, inexistente o revocada ( |
FORBIDDEN | 403 | Permiso o plan insuficiente por un motivo distinto de |
NOT_FOUND | 404 | El recurso no existe o no es de esta cuenta ( |
CONFLICT | 409 | Reservado para escrituras, que v1 no tiene. |
VALIDATION_ERROR | 422 | Parámetro inválido ( El archivo supera los 25 MiB ( |
INVALID_CURSOR | 422 | Parámetro inválido ( |
CURSOR_EXPIRED | 422 | Parámetro inválido ( |
INVALID_FILE_TOKEN | 401 | Enlace inválido, vencido o de una clave revocada ( |
RATE_LIMITED | 429 | Se superó el límite de peticiones ( |
DEPENDENCY_UNAVAILABLE | 503 | Servicio no disponible temporalmente ( |
COORDINATION_UNAVAILABLE | 503 | Reservado para escrituras, que v1 no tiene. |
LOCAL_CAPACITY | 503 | Servicio no disponible temporalmente ( |
REQUEST_REJECTED | 4xx | La petición se rechazó antes de llegar a una operación, por ejemplo con un método distinto de |
SCOPE_REQUIRED | 403 | La clave no tiene el permiso de la operación ( |
API_PLAN_REQUIRED | 403 | La clave no tiene el permiso de la operación ( |
ACCESS_DENIED | 403 | La clave no tiene el permiso de la operación ( |
FILE_TOO_LARGE | 422 | El archivo supera los 25 MiB ( |
Qué hacer con cada estado
| Estado | Qué hacer |
|---|---|
401 | No reintentes con la misma clave. Revisa la cabecera o crea otra clave. En una descarga (INVALID_FILE_TOKEN), pide el comprobante otra vez para obtener un enlace nuevo. |
403 | No reintentes. Falta un permiso en la clave (SCOPE_REQUIRED), el plan no incluye la API (API_PLAN_REQUIRED) o la cuenta no tiene acceso activo (ACCESS_DENIED). |
404 | El recurso no existe o no es de tu cuenta; la API no distingue entre los dos casos. |
422 | Corrige la petición. Con CURSOR_EXPIRED, vuelve a la primera página; con INVALID_CURSOR, repite los mismos filtros que la página anterior. |
429 | Espera los segundos de Retry-After y reintenta. Ver Límites de uso. |
503 | Fallo pasajero del servicio. Espera los segundos de Retry-After y reintenta. |
Una respuesta 200 nunca lleva un error dentro: si el estado es 2xx, el cuerpo es el recurso.