API reference · v1

Errors & limits

Errors and limits of the XEYE API: the shared error envelope, every code, retries, idempotency and how to get help.

Updated on October 14, 2026

The error envelope

All errors, management and search alike, share the same JSON body: status, error (HTTP phrase), code (a stable identifier for your code), message (English text that may change) and, on validation errors, details with the reason per field. Branch on code, not on message.

403

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"
}

An invalid body in the management API answers 400 (VALIDATION_FAILED with details; MALFORMED_BODY if the JSON cannot be read; INVALID_ARGUMENT for an unsupported value); the search service, a separate service, answers 422 for the same. Unknown fields are ignored in management and rejected in search.

400 · details

{
  "status": 400,
  "error": "Bad Request",
  "code": "VALIDATION_FAILED",
  "message": "Validation failed",
  "details": { "name": "must not be blank" },
  "timestamp": "2026-10-14T09:31:02.004Z"
}

Codes

HTTP	code	Meaning	What to do
400	VALIDATION_FAILED · MALFORMED_BODY · INVALID_ARGUMENT · INVALID_PARAMETER	Invalid body or parameter in the management API (per-field details in VALIDATION_FAILED; INVALID_PARAMETER when a path id is not numeric).	Fix the field named in details, or the parameter.
401	API_KEY_MISSING · API_KEY_INVALID · API_KEY_EXPIRED	Missing X-API-Key header (API_KEY_MISSING), key does not exist or was revoked (API_KEY_INVALID) or has expired (API_KEY_EXPIRED).	Check the key; if it expired or was deleted, create a new one in the console.
402	INSUFFICIENT_CREDIT · CREDIT_EXHAUSTED	Not enough credit to launch the training (details.required and details.balance), or the account has no credit for searches (CREDIT_EXHAUSTED).	Top up credit from the console; the pending training is kept.
403	API_KEY_SCOPE · LIST_NOT_PUBLIC	The key lacks the scope the endpoint requires (API_KEY_SCOPE), or the searched list is private (LIST_NOT_PUBLIC).	Edit the key permissions in the console, or make the list public.
404	NOT_FOUND · LIST_NOT_FOUND	The resource does not exist or does not belong to your account (NOT_FOUND), or there is no list with that name (LIST_NOT_FOUND). An element under a list that is not its own is 404 too.	Check the ids and the list_name; “does not exist” and “not yours” are never told apart.
409	CONCURRENT_MODIFICATION · CONFLICT	Two requests modified the same resource at once (CONCURRENT_MODIFICATION), or the list already has a training queued or running (CONFLICT).	Re-read the resource and retry; or wait for the training to finish.
413	REQUEST_TOO_LARGE	Body too large: 1 MB in general, 16 MB for the element batch, 16 KB for search (REQUEST_TOO_LARGE).	Split the batch or send only the documented fields.
422	VALIDATION_FAILED	Search only: invalid body or unknown fields (VALIDATION_FAILED with details).	Look at details: it names the field and the reason.
429	RATE_LIMITED	Quota exhausted: per key in management, per account in search, or per IP after several failed authentications (RATE_LIMITED).	Wait the Retry-After seconds; watch X-RateLimit-Remaining to stay under the limit.
503	SERVICE_NOT_READY · BACKEND_UNAVAILABLE · SERVICE_UNAVAILABLE	The search service is starting or cannot reach the backend (SERVICE_NOT_READY, BACKEND_UNAVAILABLE), or a service the management depends on is not answering (SERVICE_UNAVAILABLE).	Retry after the Retry-After seconds; if it persists, check the status page.

Retries

Retry only 429 (after Retry-After), 503 and network errors, with exponential backoff and a cap on attempts. Do not retry any other 4xx: the request is wrong and will keep failing. GET, PATCH, DELETE and batch-delete are idempotent; repeating a creation POST after a timeout may duplicate the element: check with GET first and clean up with batch-delete.

If you need help

Every response carries an X-Request-Id header. Keep it with your logs and send it to info@xeye.es when reporting a problem: it lets us follow the request end to end.

Next: Best practices & FAQ