# Handle API errors

Source: https://cicora.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.

## FAQ

### What is cicora.ai?

cicora.ai is a multi-model AI workspace and compatible API for chat, text, images, video, coding tools, and teams. Start with the [overview](/en.md), [documentation](/en/docs.md), or [model catalog](/en/models.md).

### How is usage billed?

Confirmed usage is charged in USD from the active workspace's prepaid balance. Use the live catalog for current model prices and the [usage guide](/en/docs/usage-costs.md) for settlement details.

### Which protocols and integrations are available?

Documentation covers OpenAI-compatible Chat Completions and Responses, Anthropic Messages, image interfaces, Claude Code, OpenCode, and Codex CLI. Compatibility does not imply support for every upstream parameter.

### Which sources are authoritative and current?

For model IDs, availability, capabilities, limits, and prices, use the [live catalog](/en/models.md). For API behavior, use the matching [documentation page](/en/docs.md). Never include API keys, private workspace data, or preview URLs in public documents.