Errors

Error shape

Use the HTTP status as the primary category. Inference failures use a bounded top-level error object; identity and request-dependency failures may use FastAPI's detail envelope.

{
  "error": {
    "code": "routing_exhausted",
    "message": "Provider temporarily unavailable",
    "metadata": {
      "error_type": "provider_unavailable",
      "retry_after_seconds": 18
    }
  }
}

Status codes

Treat each class deliberately.

• 401 — missing or invalid bearer credential
• 402 — cumulative spend denied by the configured budget authority
• 403 — tenant, product, policy, scope or other admission denied
• 404 — catalogue record not found
• 422 — request body failed validation
• 429 — service quota exceeded or every eligible provider rate limited
• 502 — non-retryable upstream provider failure
• 503 — routing or a required authority unavailable

Provider and upstream errors

A policy route may attempt eligible fallbacks before returning a normalized error. Provider bodies, URLs, deployment identifiers and credentials never belong in the public response.

{
  "error": {
    "code": "routing_exhausted",
    "message": "Provider temporarily unavailable",
    "metadata": {"error_type": "provider_unavailable"}
  }
}

Retry guidance

Retry only requests that are safe to repeat. Use exponential backoff with jitter, respect the normalized Retry-After header when present, cap attempts, and stop at the user-facing deadline.

• Do not retry 401, 402, 403, 404 or 422 unchanged
• Retry 429 after the supplied delay
• Treat 502 as non-retryable; retry an explicitly temporary 503 only within a strict attempt budget
• Treat interrupted streams as partial output, not a guaranteed zero-result request

Operational logging

Record timestamp, environment, route, HTTP status, safe error code and request correlation identifier. Never record bearer tokens, provider secrets or unredacted sensitive content.