# Handle API errors

Source: https://provod.ai/en/docs/errors

On failure, preserve the HTTP status and API response before reading the public code. Do not replace the exact response with an assumption based on status alone because the same status can require different actions.

## Read an OpenAI-compatible error

A normal Chat Completions failure has an `error` object. For example, temporary model unavailability uses this public shape:

```json
{
  "error": {
    "code": "MODEL_NOT_AVAILABLE",
    "message": "The selected model is temporarily unavailable. Please try again.",
    "param": null,
    "type": "server_error"
  }
}
```

Use `error.code` for client decisions, `error.message` for readable diagnostics, `error.param` for the related field, and `error.type` for the error class. Do not parse message text when a public code is available.

Some model-validation failures also expose stable top-level `code` and `model` fields. Billing failures can use stable top-level fields too: insufficient balance reports current and required amounts, while a key limit reports `API_KEY_SPEND_LIMIT_EXCEEDED`, its period, amounts, and `resetAt`. Preserve the actual response body instead of assuming every error uses one nested shape.

*A structured error returns from the API to the calling application.*

*Branch on HTTP status and public code rather than private causes.*

## Choose an action from status and code

| Signal           | What to inspect                                                            | Action                                                                                                                                                                                                 |
| ---------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| HTTP `400`       | `error.code`, `error.param`, `model`, and request body                     | Correct the format, context, output limit, or unsupported capability. Do not repeat the unchanged request.                                                                                             |
| HTTP `401`       | Bearer header and key state                                                | Use a valid key from the active workspace. Revoke and replace a lost or exposed key.                                                                                                                   |
| HTTP `402`       | Available balance and active reservations                                  | Let active reservations complete or release and check available balance again before you reduce the request or top up the workspace.                                                                   |
| HTTP `403`       | Public code and workspace role                                             | Correct access permissions. Only when the code is `FIRST_TOP_UP_REQUIRED`, use the returned `topUpUrl` for the first real top-up.                                                                      |
| HTTP `429`       | Top-level `code` and `resetAt` when present                                | For `API_KEY_SPEND_LIMIT_EXCEEDED`, wait for `resetAt` or change the limit; retry a transient limit only under the [limits and retries](/en/docs/limits) guidance.                                     |
| HTTP `5xx`       | Public code and whether output has started                                 | Follow the [bounded retry rules](/en/docs/limits). After any output, do not start an automatic duplicate.                                                                                              |
| No HTTP response | Client network, DNS, TLS, cancellation, and whether partial output arrived | No output does not confirm that the request was not accepted. Check [Usage](/en/docs/usage-costs), the exact time, and model, then make an explicit decision under the [retry rules](/en/docs/limits). |

`FIRST_TOP_UP_REQUIRED` and `topUpUrl` are shipped fields for a model lock in an applicable personal workspace. Do not treat every `403` as a request to add balance because insufficient workspace permission can use the same status.

## Distinguish image errors

Image option validation uses `MODEL_PARAMETER_COMBINATION_INVALID` when a model cannot accept the requested option combination and `MODEL_CAPABILITY_METADATA_UNAVAILABLE` when capability metadata cannot currently be checked.

Current image execution codes are `IMAGE_UPSTREAM_INVALID_REQUEST`, `IMAGE_UPSTREAM_INVALID_RESPONSE`, `IMAGE_UPSTREAM_RATE_LIMITED`, `IMAGE_UPSTREAM_UNAVAILABLE`, `IMAGE_UPSTREAM_FAILED`, `IMAGE_ARTIFACT_STORAGE_FAILED`, and `IMAGE_REQUEST_ABORTED`. A client should show the safe message and branch on the public code without exposing an external service name or response.

## Prepare safe support evidence

Before contacting [support](/en/contact), collect:

1. exact HTTP status, public code, and safe message;
2. API endpoint and exact model ID;
3. request identifier when the client or Usage view supplies one;
4. exact time with timezone and the client or tool name and version;
5. key name and visible masked prefix;
6. a redacted request body only when it is necessary to reproduce the failure.

**Do not send secrets or private diagnostics**


Never include a complete API key, password, payment credentials, sensitive prompt, external service names, internal routes, or raw external responses. The public error and safe identifiers are sufficient for investigation.
