Errors
Every error is a JSON envelope with a status, a human-readable message, and a stable machine-readable code where one applies.
The envelope
example: 402
{
"error": {
"statusCode": 402,
"message": "Insufficient credit",
"code": "insufficient_credit",
"required": "125000",
"available": "20000"
}
}Amounts in error payloads are micro-USD strings (1,000,000 = $1), the same fixed-point unit the ledger uses.
Status codes
| Status | Meaning | What to do |
|---|---|---|
| 400 | The request violates the model’s contract (an unsupported attribute, a value out of bounds). Nothing was charged. | Fix the request; the message names the offending field. |
| 401 | Missing, invalid, revoked or expired API key. | Check the Authorization header and the key’s status. |
| 402 insufficient_credit | The account’s available credit cannot cover the request’s worst case. | Add credit, or lower max_tokens to shrink the worst case. |
| 403 | The key is not allowed to use this model, or the account is frozen. | Check the key’s allowlist and the account status. |
| 404 | Unknown model, job or artifact, or one that belongs to another account. | Check the id against the catalog or your own resources. |
| 409 | Request state conflict; the request needs review rather than a blind retry. | Do not retry automatically; check the job or contact support. |
| 422 | The request body failed validation before dispatch. | The issues array lists each field and what is wrong with it. |
| 429 + Retry-After | The key’s requests-per-minute limit was reached. | Wait for the seconds given in the Retry-After header. |
| 5xx / 503 | The platform or network cannot serve this right now, including no provider being available for the model. Nothing was charged. | Retry with backoff; check the model’s provider count on the catalog. |
Errors and your money
A request rejected before reaching a provider never charges. When an outcome is genuinely ambiguous, for example a connection lost mid-generation, the hold stays until the provider’s receipt resolves what was actually done; the receipt amount is what you pay, and a hold with no receipt is released.