> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindcase.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Every error code, whether to retry, and how to back off.

Every HTTP error has the same shape. Branch on `error.code`: it is stable and never reworded. `error.message` is for people and may change.

```json theme={null}
{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance is $0. Please top up at https://console.mindcase.co/account?tab=billing (this API costs $0.0020/row).",
    "request_id": "req_6f1c2ab4e0d94c7f9a3b1d5e8c7f2a10",
    "retryable": false,
    "fault": "input",
    "details": {
      "balance_usd": 0,
      "price_per_row_usd": 0.002,
      "top_up_url": "https://console.mindcase.co/account?tab=billing"
    }
  }
}
```

* `retryable`: whether the same request, unchanged, can succeed later.
* `request_id`: quote it when you contact support.
* `fault`: `input` (fix the request or add balance) or `mindcase` (our side).
* `details`: extra fields that depend on the code.

Runs that start and then fail are reported on the job, not as HTTP errors. See [Jobs and results](https://docs.mindcase.co/jobs.md#why-a-run-failed).

## Error codes

| HTTP | `error.code` | Retry? | Meaning |
| - | - | - | - |
| 400 | `bad_request` | no | The request couldn't be understood |
| 400 | `invalid_idempotency_key` | no | The `Idempotency-Key` header must be 8 to 255 printable characters |
| 401 | `missing_api_key` | no | No API key was sent |
| 401 | `invalid_api_key` | no | The key isn't recognised |
| 401 | `revoked_api_key` | no | The key was revoked. Create a new one |
| 401 | `expired_api_key` | no | The key was replaced and its grace period ended |
| 401 | `unauthorized` | no | No valid credentials were sent |
| 402 | `insufficient_balance` | after top-up | Your wallet is empty |
| 402 | `funded_balance_required` | after top-up | This API needs a funded balance |
| 403 | `forbidden` | no | These credentials can't do this |
| 404 | `agent_not_found` | no | Unknown API `group/slug` |
| 404 | `job_not_found` | no | Unknown job, or not yours |
| 404 | `not_found` | no | No such route |
| 405 | `method_not_allowed` | no | This route doesn't accept that method |
| 409 | `job_not_ready` | yes | The job hasn't finished. `details.status` has its state |
| 409 | `idempotency_in_progress` | yes | A request with this `Idempotency-Key` is still being processed |
| 409 | `conflict` | no | The request conflicts with the current state |
| 410 | `agent_retired` | no | This API has been removed |
| 410 | `gone` | no | This resource no longer exists |
| 413 | `payload_too_large` | no | The request body is too large |
| 415 | `unsupported_media_type` | no | Send `Content-Type: application/json` |
| 422 | `invalid_params` | no | Inputs were rejected. `details.errors` lists each field with its own `code`, `field` and `message` |
| 422 | `idempotency_key_reused` | no | That `Idempotency-Key` was used for a different request |
| 429 | `rate_limited` | yes | Too many requests this minute |
| 429 | `too_many_concurrent_runs` | yes | Too many runs in progress. Start the next when one finishes |
| 500 | `internal_error` | yes | Something unexpected failed on our side |
| 502 | `bad_gateway` | yes | A service we depend on returned a bad response |
| 503 | `balance_unavailable` | yes | We couldn't read your balance. This says nothing about your money |
| 503 | `service_unavailable` | yes | Temporarily unavailable |
| 504 | `gateway_timeout` | yes | A service we depend on timed out |

## Retrying

| Situation | How you see it | Wait |
| - | - | - |
| Rate limited | HTTP 429 `rate_limited` | `Retry-After` |
| Too many runs in progress | HTTP 429 `too_many_concurrent_runs` | `Retry-After` (5s), or until a run finishes |
| We couldn't read your balance | HTTP 503, or a `failed` job with `balance_unavailable` | 5s |
| Something failed on our side | `failed` job with `retryable: true` | 30s |
| Bad parameters | HTTP 422 | Fix them first |
| Not enough balance | HTTP 402, or `rejected_balance` | Add balance first |
| Bad API key | HTTP 401 | Fix the key first |

Retry only when `retryable` is `true`, and wait `Retry-After` (also in `details.retry_after_seconds`) first. With no wait time, back off exponentially from 0.5 seconds with jitter, up to 30 seconds, and stop after about five attempts. Send an [`Idempotency-Key`](https://docs.mindcase.co/running-apis#retrying-safely-idempotency-key) on `POST .../run` so a retry can't start and charge a second run.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.