Error codes
Every upstream provider's native errors are normalized into ONE envelope: { error: { message, type, code } } — the same shape the OpenAI SDK expects. Secrets are scrubbed from every message.
| code | HTTP | Meaning + what to do |
|---|---|---|
| auth | 401 | Missing/invalid API key or session. Keys are org-scoped Bearer tokens. |
| key_revoked | 401 | The API key was revoked in the dashboard. |
| insufficient_credits | 402 | Org balance too low — request a top-up in the dashboard. |
| spend_cap_exceeded | 402 | This key hit its spend cap (set per key; defaults on). |
| forbidden | 403 | Role/membership/CSRF gate: not a platform admin, not a member of that operator/tenant, or a cookie-authed mutation without x-nr-csrf. |
| invalid_request | 400 | Malformed body or an illegal combination (e.g. a key jurisdiction that would WIDEN the org pin; fallbacks + models together on /messages). |
| context_length | 400 | Prompt exceeds the endpoint's context window — pick :extended or a bigger model. |
| content_filter | 400 | The upstream refused the content. |
| rate_limit | 429 | Per-IP or per-key rate limit; back off and retry. |
| no_eligible_endpoint | 503 | Nothing satisfies your sovereignty pin + filters. The response lists WHY each endpoint was excluded — loosen the pin consciously, never silently. |
| upstream_timeout | 504 | The upstream failed/timed out and all fallbacks were exhausted; hops are in the attestation. |
| not_implemented | 501 | Declared surface not built yet (honest stub). |
| byok_invalid | 502 | Your BYOK provider key was rejected upstream. |
| internal | 500 | NeuralRing-side fault — the requestId in the envelope links the attestation trail. |