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

# Errors

> Every error is JSON with a stable type, a message, and detail when there is more to say.

```json theme={null}
{
  "error": {
    "type": "invalid_request",
    "message": "request validation failed",
    "detail": [{ "path": ["max_results"], "message": "Too big: expected number to be <=100" }]
  }
}
```

| HTTP | `error.type`              | When                                                                                                                 |
| ---- | ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| 400  | `invalid_request`         | The body failed validation, or `strict: true` met a parameter the provider cannot honour. `detail` lists the issues. |
| 401  | `unauthorized`            | Missing, malformed, or revoked API key.                                                                              |
| 402  | `insufficient_credits`    | Your balance is at or below zero. Nothing was charged. Top up in the dashboard.                                      |
| 404  | `not_found`               | Unknown route, or a job id that does not exist or belongs to another account.                                        |
| 501  | `provider_not_available`  | The provider does not offer this tool, for example a search-only engine on Extract.                                  |
| 502  | `provider_error`          | The provider returned an error. `detail` carries its response body verbatim. With `fusion`, every member failed.     |
| 503  | `provider_not_configured` | The named provider has no key on this deployment, or transcription's durable execution is unavailable.               |

## Handling them

* **Retry 502 and 503** with backoff, or switch `provider`. They describe the provider, not your request.
* **Do not retry 400, 401, or 402.** Fix the request, the key, or the balance.
* **Transcription jobs fail in the job, not the submission.** A 202 means the job was accepted; a provider failure later shows up as `status: "failed"` with `error` on the job, and you are not charged.
* **Include the response `id`** (`srch_…`, `ext_…`, `job_…`) when writing to support. Every request is traceable by it.