# Errors and retry decisions

Source: https://convergingthought.com/docs/api-reference/errors

> Distinguish rejected requests, failed jobs, and outcomes that need reconciliation.



An HTTP error means the current API request did not return a successful response. A job error describes an admitted operation. They are related but not interchangeable: a successful `GET /v1/jobs/{id}` can return a job whose status is `failed`.

## HTTP error envelope [#http-error-envelope]

```json
{
  "error": {
    "code": "insufficient_credits",
    "retryable": false,
    "request_id": "HTTP_REQUEST_ID"
  }
}
```

The request ID is also returned in `X-Request-Id`. Preserve it with the method, route, status, and timestamp. Avoid logging authorization headers or model content to diagnose an error.

## Error reference [#error-reference]

| HTTP | Code                      | Meaning and next action                                                                                                   |
| ---- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| 401  | `unauthorized`            | Missing, malformed, expired, or revoked key. Check the server credential.                                                 |
| 403  | `server_keys_only`        | The request carries an Origin header. Move the API call to your server.                                                   |
| 403  | `insufficient_scope`      | The key lacks the operation's scope. Use the correct credential.                                                          |
| 403  | `preview_only`            | Hosted model admission is disabled. Retrying cannot enable execution.                                                     |
| 402  | `insufficient_credits`    | Available balance cannot cover the reservation. Fund the project when live billing is enabled.                            |
| 402  | `spend_limit_exceeded`    | Current spend plus reservations would exceed the hard monthly limit. Review Settings.                                     |
| 402  | `project_frozen`          | The balance needs reconciliation, for example after a refund. Resolve billing.                                            |
| 403  | `tenant_scope_mismatch`   | The request selects a tenant outside the key’s fixed restriction. Use the authorized tenant or correct server credential. |
| 404  | `not_found`               | Unknown route or resource, or resource outside the key's project. Verify the ID and project.                              |
| 409  | `idempotency_conflict`    | The same key was used for different work. Recover the original payload or choose a new key for a genuinely new operation. |
| 409  | `activation_conflict`     | The expected active version no longer matches. Read current state and make a release decision.                            |
| 409  | `adapter_expired`         | Required adapter retention has expired. Inspect the route and contact support.                                            |
| 413  | `body_too_large`          | JSON body exceeds the byte limit. Reduce the request.                                                                     |
| 422  | `invalid_request`         | Invalid JSON, content type, header, field, or semantic constraint. Check the endpoint schema.                             |
| 429  | `rate_limited`            | New admission limit reached. Honor Retry-After and back off.                                                              |
| 503  | `platform_not_configured` | A required platform dependency is unavailable or unconfigured. Retry reads conservatively; preserve write identity.       |
| 500  | `internal_error`          | An unexpected server error occurred. Keep the request ID and recover writes idempotently.                                 |

Console-specific operations can also report `invalid_origin` or `billing_not_configured`. They are not reasons to change public API key scopes or bypass the console's session boundary.

## What retryable means [#what-retryable-means]

The public HTTP wrapper marks `rate_limited`, `platform_not_configured`, and `internal_error` as retryable. That flag describes whether a later transport attempt might succeed. It does not authorize a new idempotency key, prove the original work never started, or cancel a job.

A non-retryable admission error can become resolvable after a deliberate change. For example, adding real credit can resolve `insufficient_credits`. If no job was admitted and the intended body is unchanged, reuse its original idempotency key after fixing the cause.

For reads, use bounded exponential backoff with jitter. For model writes, retry only the same intent with the same key and body. Set a ceiling on attempts so a configuration failure does not become an endless loop.

## Job errors [#job-errors]

A job's `error` contains `code` and `retryable`; its ID already identifies the durable operation. Worker codes can indicate curriculum failure, teacher validation failure, expired state, dispatch uncertainty, or provider execution problems. Treat the code as diagnostic and inspect status and settlement before deciding what to do.

`reconciliation_required` needs investigation even if your client library throws an exception. Do not catch it in a generic retry loop that submits a new learning or inference job. Preserve the original ID and follow [job recovery](/docs/troubleshooting/jobs).

## Unknown codes [#unknown-codes]

Display a useful generic failure when a code is unrecognized, and preserve the code in restricted operational logs. Avoid branching on human-readable text or raw provider messages. The server intentionally returns bounded machine-readable errors rather than private provider detail.

Use [safe diagnostics](/docs/troubleshooting/diagnostics) to report a reproducible problem without including keys, prompts, source passages, or answers.