Errors
Errors use the OpenAI envelope: a JSON body with an error object whose code matches the HTTP status:
{ "error": { "code": 402, "message": "Insufficient wallet balance — top up to continue.", "type": "insufficient_quota", "param": null } }| Status | Type | When |
|---|---|---|
| 401 | authentication_error | Missing or invalid API key. |
| 403 | permission_error | This key is not a developer key. An agent key, pinned to one text model, tried to reach a media endpoint. |
| 403 | model_not_permitted | The model exists, but this key's scope does not include it. |
| 402 | insufficient_quota | Wallet balance is empty, or the key hit its monthly spend cap. |
| 402 | insufficient_funds | A different case than insufficient_quota above: the pre-flight balance check passed, but reserving this specific request's price failed at submit time (e.g. a concurrent request drained the balance first). |
| 404 | model_not_found | The model value is not a published AI HUB model. |
| 404 | brand_not_found | The brand id is missing, belongs to another account, or is malformed. |
| 429 | rate_limit_exceeded | The key's own request-rate limit was exceeded, or every available vendor route for the model is being rate-limited. Honor the Retry-After header in either case. Rate limits. |
| 400 | invalid_request_error | The request body is malformed (e.g. missing messages), or the model provider rejected the request as sent. The provider's own type/message is passed through unchanged. |
| 408 | timeout | The upstream model took too long to respond. Retry. |
| 409 | idempotency_conflict | A duplicate arrived on the same key while the first request was still running, or the key was reused on an endpoint that cannot be replayed. Use a new key. |
| 422 | idempotency_key_reused | The key was reused with a request body that does not match the first request sent under that key. |
| 422 | published_not_serving | The model is published but this account cannot currently reach it because the SKU is vendor-locked. Please try again later or select another model. video submission. |
| 422 | model_capability_unsupported | The request is well-formed, but this model does not support the attachment role or option sent. Support for first_frame, reference and watermark differs per model. attachment roles by model. |
| 502 | upstream_error | The upstream model returned a server error or an auth or credit fault, or was unreachable, and every available route failed. Retry. |
| 503 | model_unavailable | The upstream model is temporarily unreachable. Retry shortly. |
A vendor outage does not always surface as an error. AI HUB automatically retries a failing model on an alternate route before giving up, and returns 408/502, or a vendor-caused 429, only when every available route for that model has failed. (The key's own request-rate limit is a separate 429, enforced before any vendor call is attempted.) Vendor error details (account identifiers, raw provider messages) are never forwarded. The generic message above is returned instead of the vendor's.
On the media endpoints, 429 rate_limit_exceeded has two unrelated causes with different remedies: the key's own per-minute request rate, and a per-user cap on images and videos generating at once. See Rate limits for how to identify which limit was reached.
Two real examples
// model doesn't exist
{ "error": { "code": 404, "message": "Model `does-not-exist` is not available.", "type": "model_not_found", "param": null } }
// missing/invalid bearer token
{ "error": { "code": 401, "message": "Invalid API key.", "type": "authentication_error", "param": null } }Budget & spend-cap errors
A 402 insufficient_quota is returned in two cases, each with its own message so that they can be told apart:
| Message | Meaning |
|---|---|
Insufficient wallet balance — top up to continue. | The account wallet is empty. A top-up on the billing page unblocks every key. |
This key reached its spend cap. | This key reached its optional monthly spend cap. Other keys keep working, and the cap can be raised or cleared on the key. |
The spend cap is a soft cap. It is checked before each call, so the request that crosses the cap still completes, and total spend can finish slightly above the cap (e.g. a $0.10 cap may settle around $0.11). If an exact limit matters, set the cap a little below the true ceiling.
Idempotency-Key
Send an Idempotency-Key header, an opaque string up to 255 characters, on any POST request (chat completions, image generations, audio speech, video generations) to make it safe to retry.
Repeating a key after the first request has completed returns the original response, unchanged, with an Idempotent-Replay: true header. The request is not billed a second time.
This also applies to a rejected request. A 400 or 422 caused by the request itself, such as a bad param or an unsupported attachment role, is stored and replayed exactly like a success. Retrying a fixed request under the SAME Idempotency-Key returns the identical old error. Send a new key once the request is fixed.
Streaming chat completions (stream: true) and /v1/audio/speech cannot be replayed. A repeat key on either one returns 409. Send a new key instead.
Reusing a key with a request body that differs from the first request returns 422 back.
A duplicate that arrives while the first request on the same key is still running returns 409 with a Retry-After header. Wait for the first request to finish rather than retrying immediately.
The case to build retry logic around: a 402, 429, 408 or a 5xx response is never stored against the key. Retrying the same key after a top-up, or after the limit or timeout has passed, runs as a fresh attempt, not a blocked replay.
Keys expire 24 hours after they are first used. After that, the same string is treated as new.
Request logs & retention
Every API call is written to an internal request log, api_request_logs, kept for 90 days and then permanently deleted. It stores metadata only: the endpoint called, the model requested, the HTTP status returned, latency, and token counts.
It never stores the content of request or response bodies.
For a billing question, this log is not the record of truth. Use the monthly statement and usage history instead, which are retained for the full statement period.