Errors

Rikaii returns standard HTTP status codes with a JSON body when something goes wrong. Always read the payload for the machine-readable error code and the message string.

Typical JSON body:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please upgrade your plan or slow down.",
  "status": 429,
  "timestamp": "2026-05-07T12:00:00Z"
}

The error field is what clients should branch on; message is operator-safe (no stack traces).

HTTP status codes

Status	Meaning
401 Unauthorized	Invalid or missing API key, or malformed Authorization header (Bearer scheme required).
402 Payment Required	Pay-as-you-go monthly spend limit reached, no payment method on file when required, or another billing prerequisite failed.
403 Forbidden	Attempted to configure bring-your-own-key (BYOK) provider keys (add, update, or remove) without an active Pro subscription. Other authenticated Dashboard or account routes may return 403 when the signed-in user lacks permission.
429 Too Many Requests	Rate limit exceeded for POST /v1/chat/completions. Retry with backoff; see Rate limits.

Other codes you may see:

Status	Meaning
400 Bad Request	Malformed JSON or invalid parameters.
503 Service Unavailable	Rate-limiting infrastructure temporarily unavailable; requests are fail-closed for protection.
500 Internal Server Error	Unexpected failure—retry later; contact support if it persists.

Related

• Authentication
• Rate limits