Error Handling
Text and Transcribe errors follow the OpenAI error format. Ark returns its own messages and keeps provider details in operator Diagnostics. Invalid API keys are rejected before model and capacity checks.
{
"error": {
"message": "Model not found",
"type": "invalid_request_error",
"param": "model",
"code": "model_not_found"
}
}| Parameter | Type | Default | Description |
|---|---|---|---|
| 400 | — | — | Invalid request (missing params, bad JSON) |
| 400 | invalid_response_format / invalid_temperature | — | Malformed JSON format option or temperature outside 0–2; rejected before inference |
| 401 | — | — | Authentication required |
| 403 | — | — | Provider/model not allowed for this key |
| 403 | account_suspended | — | The API key owner is suspended. Contact support; requests are not served or billed. |
| 404 | — | — | Model not found |
| 402 | insufficient_credits / budget_exceeded / model_not_priced | — | Insufficient balance, a spending cap, or an unpriced model |
| 422 | unsupported_option | Text | The selected model does not support one or more requested options |
| 422 | context_limit_exceeded | Text | Shorten the input or lower max_tokens |
| 422 | reasoning_required | Text | Set reasoning_effort to low or higher, or leave it out |
| 429 | — | — | Ark API key request limit exceeded. Honour Retry-After (seconds). |
| 400 | invalid_request_parameters | Text | The model rejected request parameters; check messages and generation options |
| 502 | upstream_connection_error | — | Connection to the generation service failed |
| 503 | upstream_unavailable | — | The generation service is temporarily unavailable |
| 504 | upstream_timeout | — | The generation service did not respond before the deadline |
| 500 | internal_error | — | Ark could not complete the request; provider details are masked |
| 429 | rate_limit_exceeded | — | The upstream provider is rate limiting this model, or its capacity is fully in use; honour Retry-After |
| 503 | no_capacity | — | No capacity is available for this model right now; honour Retry-After |
| 503 | state_unavailable | — | Request capacity is temporarily unavailable; honour Retry-After |
Unsupported model options
When a selected model does not support an option, Ark returns 422 unsupported_option instead of a generic server error. Adjust the model-specific options before retrying. Unexpected service errors still return 500 internal_error; provider messages and credentials are not exposed.
{
"error": {
"message": "This model does not support one or more requested options.",
"type": "invalid_request_error",
"param": null,
"code": "unsupported_option"
}
}Capacity failures
Temporary account saturation waits briefly for a slot. If none becomes available, or the upstream provider is rate limiting, the request returns 429 rate_limit_exceeded; when no capacity exists at all it returns 503 no_capacity. A capacity service failure returns 503 state_unavailable. Both responses include Retry-After in seconds. Retry after that delay; validation errors require changing the request. A stream that has already started is never automatically restarted.
Streaming failures
Chat Completions, Responses and Messages check the initial response before committing the stream. An error detected at that point can return an HTTP error status, including 422 unsupported_option, 429 rate_limit_exceeded, 503 no_capacity or 500 internal_error.
After a text stream starts, failures arrive as a safe error object in an SSE data: event; the HTTP status can no longer change. The same public error codes are preserved, while unexpected service errors become internal_error. Clients must inspect stream events as well as the initial HTTP status.
JSON repair outcomes
A failed JSON repair is not an inference error: the original completion is returned with its existing status, usage and finish reason. Inspect X-Ark-JSON-Repair and parse the content yourself. See Automatic JSON repair for failure and skip reasons.