Errors & conventions
Response envelope
Every response is JSON with a status field.
200 Success
{ "status": "success", "...": "endpoint-specific fields" }402 Error
{ "status": "error", "code": "QUOTA_EXCEEDED", "message": "Out of credits" }The code is a stable, machine‑readable string — branch on it rather than on the
human‑readable message.
Error codes
| HTTP | code | Meaning |
|---|---|---|
| 400 | (varies) | Bad input |
| 401 | AUTH_MISSING | No Bearer token |
| 401 | AUTH_INVALID | Bad, expired or revoked credential |
| 402 | QUOTA_EXCEEDED | Out of credits — top up or upgrade |
| 402 | BILLING_OVERDUE | An Enterprise (postpaid) invoice is unpaid past its pause date, so new billable calls are refused until it is paid. Reading data, reports and paying still work. Only that key is paused when the invoice is the key’s own — see Billing |
| 409 | UNPAID_USAGE_INVOICE | Credits cannot be bought while a usage invoice is open: pay the invoice first |
| 402 | KEY_CREDITS_EXHAUSTED | This API key has used all the credits assigned to it (remaining says what is left). Ask the account owner to assign more — see Account & usage |
| 403 | SCOPE_FORBIDDEN | Key lacks the scope for that service — see Scopes |
| 403 | KEY_MANAGEMENT_REQUIRES_SESSION | An API key tried to create, list or edit keys, or to revoke a key other than itself. Sign in to the dashboard |
| 403 | VERIFICATION_REQUIRED | Your organization has to complete identity verification before using this. No plan upgrade gets past it |
| 404 | UNKNOWN_SERVICE | No such service |
| 413 | PAYLOAD_TOO_LARGE | Upload over the size limit (15 MB default) |
| 415 | UNSUPPORTED_MEDIA_TYPE | File type not allowed |
| 429 | RATE_LIMITED | Too many requests this minute |
| 429 | USAGE_LIMIT_REACHED | Your daily or monthly credit cap is reached. This is not an empty balance: topping up does not lift it |
Some endpoints add codes of their own, such as INVALID_MODEL on Responses; the reference page for each of those endpoints lists them.
Your own model servers
On Enterprise, a conversation, agent or /v1/responses call that runs on your organization’s own model server (Your own model servers) can also answer with these. They describe your server, so they say what to fix there. Nothing is charged.
| HTTP | code | Meaning |
|---|---|---|
| 409 | PRIVATE_MODEL_UNAVAILABLE | The model was switched off or its server removed. The conversation does not move to another model by itself |
| 502 | PRIVATE_MODEL_UNREACHABLE | Your server could not be reached |
| 504 | PRIVATE_MODEL_TIMEOUT | Your server did not start answering in time (it may still be loading the model) |
| 502 | PRIVATE_MODEL_AUTH | Your server refused the key or headers stored for it |
| 502 | PRIVATE_MODEL_BUSY | All of your server’s request slots stayed busy |
| 502 | PRIVATE_MODEL_BAD_RESPONSE | The answer did not follow the /v1/chat/completions standard, or the model name is wrong |
| 502 | PRIVATE_MODEL_CONTEXT_OVERFLOW | The conversation does not fit the model’s context window |
| 403 | CLOUD_FEATURE_OFF | Your organization keeps these conversations off Vanguard’s cloud AI, and the feature asked for would use it |
Rate limiting
Rate‑limited responses (429) include headers so you can back off gracefully:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per minute |
X-RateLimit-Remaining | Requests left in the current window |
When you hit 429, wait until the next minute before retrying. For batch workloads,
spread requests evenly rather than bursting.