Errors
Error responses follow the OpenAI shape, so existing SDK error handlers keep working. Every error carries a typed code in error.type so you can branch on it without string-matching the message.
{
"error": {
"message": "Missing or invalid API key. Include your API key as: Authorization: Bearer sk-...",
"type": "authentication_error",
"code": "authentication_error",
"param": null
}
}
The status / type table
| HTTP | error.type |
When it fires | What to do |
|---|---|---|---|
| 401 | authentication_error |
Missing, malformed, expired, or revoked key | Check the Authorization header and rotate the key if needed. |
| 402 | insufficient_credits |
Balance or monthly cap exhausted | Top up or raise the cap in the dashboard. |
| 404 | model_not_found |
The model ID is not in the catalogue and cannot be auto-deployed | Call /v1/models for the current list, or fix the typo. |
| 202 | model_deploying |
The requested model is being provisioned on a spot GPU | Retry after the Retry-After header interval (typically 3-10 minutes). See below. |
| 502 | upstream_error |
Every eligible provider failed for this request | Retry. If persistent, open a support ticket with the request ID. |
| 429 | rate_limit |
Per-key rate limit (planned, not yet enforced) | Back off and retry with jitter. |
| 500 | server_error |
Something internal went wrong | Retry with jitter; if it persists, tell support. |
202 model_deploying
Some models are served on-demand via spot GPUs and are not warm 24/7. The first request triggers a deployment (GPU provisioning + model loading). A credit hold is placed on your account for the minimum session cost before provisioning begins.
The response includes a Retry-After header with the estimated wait time in seconds. Typical cold-start times are 3-10 minutes depending on the model size and GPU availability.
{
"status": "deploying",
"message": "Model 'meta-llama/Llama-3.3-70B-Instruct' is being deployed on a spot GPU. Estimated ready in ~5 minutes.",
"model": "meta-llama/Llama-3.3-70B-Instruct",
"type": "model_deploying",
"estimated_ready_seconds": 300,
"already_queued": false,
"deployment_status": "provisioning",
"deployment_provider": "gpu-provider"
}
Check GET /v1/models to see which models are currently instant (no wait), deploying (in progress), or cold (will trigger a deploy). Use the Retry-After header value for your retry interval. The OpenAI SDK’s default retry logic will not handle 202 responses — add a wrapper if you depend on cold-starting these models.
For the full cold-start flow, credit holds, and GPU billing, see the GPU Spot Marketplace docs.
If you don’t have enough credits for the minimum GPU session, you’ll receive a 402 instead (see below).
402 insufficient_credits
{
"error": {
"message": "Insufficient credits. Your balance is $0.12. Add credits at https://app.aivory.net/billing.",
"type": "insufficient_credits",
"code": "insufficient_credits"
}
}
The message includes the live balance. See Billing for top-up and cap rules.
502 upstream_error
This means every eligible provider failed for this request. The response carries the error details so you can see what went wrong. Most common cause: the model was briefly out of capacity everywhere. Retry a few seconds later.
Streaming errors
If something goes wrong mid-stream, the error is sent as a final SSE data frame:
…followed by data: [DONE]. You are billed only for the tokens that made it to you before the error.
The param field
OpenAI uses error.param to name the offending request field. We do too when we can identify it. Expect null for most network-level failures.