API

Errors and rate limits

Status codes, error bodies, and how meters and the wallet produce 402s.

Errors use the OpenAI error envelope: a stable error.code you can branch on, an error.type category, a human error.message, and error.param naming the exhausted meter window when relevant.

json

{
  "error": {
    "message": "plan limit reached for the 5h window",
    "type": "insufficient_quota",
    "param": "5h",
    "code": "plan_limit_reached"
  }
}

Status codes#

Status	Code	Type	Meaning
400	`invalid_request`	`invalid_request_error`	Malformed body, unknown field, unsupported content part
400	`model_not_found`	`invalid_request_error`	Unknown model id, or a model this key may not use
400	`extraction_blocked`	`invalid_request_error`	The request was classified as an attempt to extract system prompts or weights
401	`invalid_api_key`	`authentication_error`	Missing, malformed or revoked key
402	`plan_limit_reached`	`insufficient_quota`	A rolling meter is full; `param` is `5h` or `weekly`
402	`insufficient_quota`	`insufficient_quota`	Prepaid wallet is empty (API keys, or usage-based Code/Chat)
429	`rate_limit_exceeded`	`rate_limit_error`	Too many concurrent requests on one key; back off and retry
500	`internal_error`	`api_error`	Retry with backoff; include the request id when contacting support
502	`upstream_error`	`api_error`	The model fleet returned an error; safe to retry
503	`cluster_at_capacity`	`api_error`	Fleet at capacity; retry after a short delay
503	`capture_unavailable`	`api_error`	Mandatory encrypted capture storage is temporarily unavailable

Meter headers#

Every response, including errors, carries the current meters so clients can show budget without an extra call:

http

x-faelith-plan: pro
x-faelith-code-5h-used: 1210000
x-faelith-code-5h-limit: 3730000
x-faelith-code-weekly-used: ...

Values are micro-dollars of list-price debit.

Budgets versus throttling#

A 402 means a budget ran out and will not clear by retrying:

Subscription keys hit the 5-hour meter first, then weekly. Wait for the window or redeem a usage reset.
API keys debit the wallet at list price. Top up under Spending.
Turning on usage-based billing lets subscription keys fall through to the wallet instead of failing.

A 429 is the only throttling signal and is per key and short-lived.

Idempotency#

Chat completions are not idempotent. If a stream drops mid-response you are billed for the tokens generated so far; resend with the partial assistant message appended if you want to continue rather than restart.

Found a mistake or a gap? Tell us and we will fix the page.