Errors (POST /v1/chat/completions)

This page documents only what your integration can receive from POST https://api.rikaii.com/v1/chat/completions: gateway-generated failures, normalized upstream errors, and the small set of infrastructure responses around the same path.

Other Dashboard or auth endpoints are out of scope here.

JSON error shape

Failures return a single JSON object with a nested error field (OpenAI-compatible):

{
  "error": {
    "message": "Rate limit exceeded. Please upgrade your plan or slow down.",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

Field	Description
error.message	Human-readable explanation for operators (no stack traces in normal operation).
error.type	High-level category (invalid_request_error, authentication_error, permission_denied, rate_limit_error, api_error, …).
error.param	Optional field name when validation targets one field; often null.
error.code	Machine-readable code—prefer this for branching in clients, with HTTP status as a fallback.

---

HTTP status reference (chat completions)

200 OK

Request accepted and fulfilled (non-streaming JSON body, or text/event-stream when stream: true). Not an error.

400 Bad Request — gateway rejected the request before a successful upstream round-trip

What it means: The JSON or routing state is not acceptable to the gateway.

Typical error.code	Typical error.type	When / example error.message patterns
bad_request	invalid_request_error	Empty messages array: "The 'messages' array is required and cannot be empty."
bad_request	invalid_request_error	Routing / BYOK configuration issues—for example unknown model with BYOK enabled, missing provider key for a custom id, BYOK routing disabled when a non-catalog id requires your key (messages reference Dashboard → Providers & Integrations).
invalid_state	invalid_request_error	Internal routing inconsistency—for example "No active AI model configured for slug: …" or "BYOK blind route missing stored key for …".
validation_failed	invalid_request_error	Bean validation on the request body failed (field list concatenated in message).

Client action: Fix the request body or Dashboard routing/BYOK configuration; do not retry the same payload expecting a different outcome unless you changed settings.

401 Unauthorized — API key authentication failed

What it means: The Authorization header is missing, not Bearer …, or the bearer token is not a valid active Rikaii API key.

error.code	error.type	Typical error.message
invalid_api_key	authentication_error	"Missing or malformed Authorization header." (malformed header / missing Bearer) or invalid/expired key after lookup.

Client action: Verify the key string, header format, and that the key was not revoked.

402 Payment Required — billing or spend guard blocked the call

What it means: The workspace or API key failed a payment or budget check before charging metered usage for this completion (or the Safety Net path could not proceed).

All of these use error.code: payment_required and error.type: invalid_request_error in the gateway’s mapper:

Situation	Example error.message (exact or substring)
Per-key spend cap hit	"API Key credit limit reached. Please increase the limit or wait for the next reset cycle."
Non‑Pro metered call with empty wallet	"Insufficient API credits. Please top up."
Calendar-month spend cap (metered)	"Monthly spend limit reached. Please increase your limit in Settings."
Overage protection: no dollars left for this completion	"Insufficient budget for this completion request."
Overage protection: estimated prompt already exhausts headroom	"Insufficient budget for this completion request (estimated prompt cost exceeds remaining cap)."
Safety Net fallback blocked by monthly cap	"Monthly spend limit reached. Cannot utilize Safety Net fallback."

Note: The message "You need a Pro subscription, a saved payment method, or wallet credits to create API keys." is returned when creating keys in the Dashboard, not on chat completions.

Client action: Top up credits, add or fix payment method in the Dashboard, raise limits, shorten prompts, or lower max_tokens / max_completion_tokens.

403 Forbidden — permission denied for the chosen route

What it means: The resolved route requires something your workspace does not satisfy (BYOK-only catalog without routing, or Safety Net blocked as permission).

error.code	error.type	Typical error.message
byok_required	permission_denied	"This model strictly requires a BYOK API Key configured in your Provider settings." (BYOK-only slug without routing-enabled provider key.)
byok_required	permission_denied	"Safety Net cannot use platform keys for BYOK-only catalog models." (primary BYOK route failed; automatic platform fallback is not allowed for that catalog row.)

The gateway maps AccessDeniedException on this path to byok_required even when the prose is Safety Net–specific—use error.message for display.

Client action: Enable Use my key for the provider, pick a non–BYOK-only model, or fix the primary route so Safety Net is not needed.

404 / 409 / 413 / 415 / … — upstream or transport semantics preserved

What it means: The LLM provider returned a non-success HTTP status. The gateway wraps the upstream body into the same nested error shape and preserves the HTTP status code when it is a standard enum (otherwise you may see 502).

Upstream HTTP	Mapped error.type / error.code (representative)
401	authentication_error / invalid_api_key
403	permission_denied / permission_denied
404	invalid_request_error / model_not_found
429	rate_limit_error / rate_limit_exceeded
5xx	api_error / upstream_error
Other 4xx	invalid_request_error / invalid_request_error

error.message is parsed from the provider’s JSON when possible.

Client action: Follow the provider’s documentation; backoff on 429/5xx; fix model or account on 401/404.

429 Too Many Requests — throttled by Rikaii (workspace or per-key)

What it means: A gateway-side limiter refused the call before exhausting upstream quota (or a separate per-key request cap applies).

Source	Typical error.code	Typical error.message
Workspace chat RPM (Redis bucket)	rate_limit_exceeded	"Rate limit exceeded. Please upgrade your plan or slow down."
Per-key request volume limit (security cap on the key)	rate_limit_exceeded	"API key security request volume limit reached for this billing period. Increase the request limit or wait for the next reset."

Both use error.type: rate_limit_error. There are no reliable Retry-After / X-RateLimit-* headers for workspace RPM—use backoff with jitter.

Client action: Slow down concurrency, wait for the key’s request window to reset. For a higher workspace RPM override, contact support@rikaii.com (see Rate limits).

500 Internal Server Error — unhandled gateway failure

What it means: An unexpected exception escaped the controller stack.

error.code	error.type	error.message
internal_error	api_error	"An unexpected error occurred. Please try again later."

Client action: Retry with backoff; contact support if persistent.

502 Bad Gateway — unusual upstream status line

What it means: Rare—upstream returned a non-standard HTTP status code that the framework could not map to a known status; the gateway still attempts to normalize the error body.

Client action: Treat like an upstream outage; retry with backoff.

503 Service Unavailable — rate limiter backend unhealthy (fail closed)

What it means: The Redis / token-bucket infrastructure for chat RPM failed open detection; the gateway refuses the request rather than allowing unlimited traffic.

error.code	error.type	error.message
rate_limit_unavailable	api_error	"Rate limiting temporarily unavailable."

Client action: Retry with backoff; if widespread, assume platform incident.

---

Success with fallback (not an error status)

When a configured fallback model or Safety Net (BYOK → platform key retry) succeeds after a retryable primary failure, the HTTP status is still 200. For non-streaming responses only, the gateway may add:

X-Rikaii-Fallback: true

Streaming responses do not currently attach this header on success. See Fallback routing for when fallbacks run.

---

Quick error.code index (chat path)

error.code	HTTP	Origin
invalid_api_key	401	Gateway auth
payment_required	402	Gateway billing / budget
byok_required	403	Gateway routing / BYOK policy
bad_request	400	Gateway validation / routing
invalid_state	400	Gateway state
validation_failed	400	Gateway bean validation
rate_limit_exceeded	429	Gateway RPM or per-key volume
rate_limit_unavailable	503	Gateway limiter outage
internal_error	500	Gateway unhandled
model_not_found	404	Upstream (normalized)
upstream_error	5xx	Upstream (normalized)
permission_denied	403	Upstream (normalized)

---

Related

• Authentication
• Rate limits
• Overage protection
• Fallback routing
• Chat completions