Skip to main content

​
Error payload shape

When a request fails, Xenovia returns a structured error body: 
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request parameters",
    "request_id": "req_1234567890"
  }
}
Use request_id to correlate API failures with platform traces and internal logs.

​
Common status codes

400 Bad Request

Invalid payload, params, or schema mismatch.

401 Unauthorized

Missing or malformed token.

403 Forbidden

Authenticated but lacking required scope.

404 Not Found

Resource missing or not visible in scope.

409 Conflict

State conflict (for example, stale resource version).

429 Too Many Requests

Rate limit exceeded.
500 Internal Server Error indicates an unexpected platform failure.

​
Rate limits

Default baseline: 100 requests per minute per user. If rate limited:
  1. Back off and retry with jitter.
  2. Respect any retry guidance returned by the API.
  3. Reduce bursty polling where possible.
Include request_id in your logs for every non-2xx response to speed up support and incident triage.

​
Reliability practices

  • Add idempotency to write operations where supported.
  • Log request and response metadata (without sensitive payloads).
  • Implement retries only for transient classes (429, selected 5xx).