Referencia de la API · v1
Errores y límites
Errores y límites de la API de XEYE: el sobre de error común, todos los códigos, reintentos, idempotencia y cómo pedir ayuda.
El sobre de error
Todos los errores, de gestión y de búsqueda, comparten el mismo cuerpo JSON: status, error (frase HTTP), code (identificador estable para tu código), message (texto en inglés que puede cambiar) y, en los de validación, details con el motivo por campo. Decide por code, no por message.
HTTP/1.1 403 Forbidden
X-Request-Id: 7f3c2a9e4b1d4e8f9a0b1c2d3e4f5a6b
{
"status": 403,
"error": "Forbidden",
"code": "API_KEY_SCOPE",
"message": "The API key does not have the scope this endpoint requires",
"timestamp": "2026-10-14T09:30:12.418Z"
}Un cuerpo inválido en la API de gestión responde 400 (VALIDATION_FAILED con details; MALFORMED_BODY si el JSON no se puede leer; INVALID_ARGUMENT para un valor no admitido); el buscador, que es otro servicio, responde 422 para lo mismo. Los campos desconocidos se ignoran en la gestión y se rechazan en la búsqueda.
{
"status": 400,
"error": "Bad Request",
"code": "VALIDATION_FAILED",
"message": "Validation failed",
"details": { "name": "must not be blank" },
"timestamp": "2026-10-14T09:31:02.004Z"
}Códigos
| HTTP | code | Significado | Qué hacer |
|---|---|---|---|
| 400 | VALIDATION_FAILED · MALFORMED_BODY · INVALID_ARGUMENT · INVALID_PARAMETER | Cuerpo o parámetro inválido en la API de gestión (details por campo en VALIDATION_FAILED; INVALID_PARAMETER si un id de la ruta no es numérico). | Corrige el campo que indica details o el parámetro. |
| 401 | API_KEY_MISSING · API_KEY_INVALID · API_KEY_EXPIRED | Falta la cabecera X-API-Key (API_KEY_MISSING), la clave no existe o fue revocada (API_KEY_INVALID) o ha caducado (API_KEY_EXPIRED). | Revisa la clave; si caducó o se borró, crea una nueva en la consola. |
| 402 | INSUFFICIENT_CREDIT · CREDIT_EXHAUSTED | El crédito no alcanza para lanzar el entrenamiento (details.required y details.balance), o la cuenta no tiene crédito para búsquedas (CREDIT_EXHAUSTED). | Recarga crédito desde la consola; el entrenamiento pendiente se conserva. |
| 403 | API_KEY_SCOPE · LIST_NOT_PUBLIC | La clave no tiene el ámbito que exige el endpoint (API_KEY_SCOPE), o la lista buscada es privada (LIST_NOT_PUBLIC). | Edita los permisos de la clave en la consola, o haz pública la lista. |
| 404 | NOT_FOUND · LIST_NOT_FOUND | El recurso no existe o no pertenece a tu cuenta (NOT_FOUND), o no hay lista con ese nombre (LIST_NOT_FOUND). Un elemento bajo una lista que no es la suya también es 404. | Comprueba los ids y el list_name; nunca se distingue entre «no existe» y «no es tuyo». |
| 409 | CONCURRENT_MODIFICATION · CONFLICT | Dos peticiones modificaron el mismo recurso a la vez (CONCURRENT_MODIFICATION), o la lista ya tiene un entrenamiento en cola o en marcha (CONFLICT). | Relee el recurso y repite; o espera a que termine el entrenamiento. |
| 413 | REQUEST_TOO_LARGE | Cuerpo demasiado grande: 1 MB en general, 16 MB en el lote de elementos, 16 KB en la búsqueda (REQUEST_TOO_LARGE). | Divide el lote o envía solo los campos documentados. |
| 422 | VALIDATION_FAILED | Solo en la búsqueda: cuerpo inválido o con campos desconocidos (VALIDATION_FAILED con details). | Mira details: indica el campo y el motivo. |
| 429 | RATE_LIMITED | Cupo agotado: por clave en la gestión, por cuenta en la búsqueda, o por IP tras varios fallos de autenticación (RATE_LIMITED). | Espera los segundos de Retry-After; vigila X-RateLimit-Remaining para no llegar al límite. |
| 503 | SERVICE_NOT_READY · BACKEND_UNAVAILABLE · SERVICE_UNAVAILABLE | El buscador arranca o no alcanza al backend (SERVICE_NOT_READY, BACKEND_UNAVAILABLE), o un servicio del que depende la gestión no responde (SERVICE_UNAVAILABLE). | Reintenta pasados los segundos de Retry-After; si persiste, consulta la página de estado. |
Reintentos
Reintenta solo los 429 (tras Retry-After), los 503 y los errores de red, con una espera exponencial y un tope de intentos. No reintentes otro 4xx: la petición está mal y seguirá fallando. GET, PATCH, DELETE y batch-delete son idempotentes; repetir un POST de creación tras un timeout puede duplicar el elemento: comprueba antes con GET y limpia con batch-delete.
Si necesitas ayuda
Cada respuesta lleva una cabecera X-Request-Id. Guárdala con tus logs y envíala a info@xeye.es al reportar un problema: permite seguir la petición de punta a punta.