Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xenovia.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Error payload shape

All non-2xx responses return a structured JSON 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.

​
Policy block format

When a request is blocked by a Rego policy, the runtime returns 403 with a policy-specific error body: 
{
  "error": {
    "message": "request blocked by policy",
    "type": "policy_violation",
    "code": "policy_block"
  }
}
The X-Xenovia-Trace-Id header is present on blocked responses. Look up that trace ID in the platform to see the full request context, the Rego rule that fired, and the policy reason string. When an intent check blocks or escalates a request, the runtime returns 403 with a generic message. The reason is never forwarded to the agent — it is logged server-side only.

​
Status codes

400 Bad Request

Invalid payload, malformed parameters, or schema mismatch. Check the message field for specifics.

401 Unauthorized

Missing, malformed, or non-xe_-prefixed token.

403 Forbidden

Valid token but insufficient access — or request blocked by policy or intent check.

404 Not Found

Resource does not exist or is not visible to the requesting key’s scope.

409 Conflict

State conflict — for example, concurrent updates to the same resource.

429 Too Many Requests

Rate limit exceeded. Back off and retry with jitter.
500 Internal Server Error indicates an unexpected platform failure. Include request_id when contacting support. 503 Service Unavailable from the runtime indicates an intent scoring failure with XENOVIA_INTENT_FAIL_MODE=closed. Default mode (open) returns 200 instead.

​
Rate limits

Default baseline: 100 requests per minute per API key. If rate limited (429):
  1. Read the Retry-After header if present.
  2. Back off with exponential jitter — do not retry immediately.
  3. Reduce bursty polling; prefer event-driven patterns.

​
Retry policy

StatusRetry?Notes
429YesRespect Retry-After; exponential backoff with jitter
500YesTransient; retry with backoff
503YesTransient; retry with backoff
400NoFix the request before retrying
401NoFix authentication before retrying
403NoPolicy block or scope issue — do not retry the same request
404NoResource does not exist

​
Reliability practices

  • Log request_id and X-Xenovia-Trace-Id for every non-2xx response.
  • Add idempotency keys to write operations where supported.
  • Implement retries only for transient classes (429, 5xx).
  • Do not retry 403 responses — they indicate a policy decision or an auth scope issue, not a transient error.