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

# Errors

> Handle lev8 HTTP errors, JSON request failures, and failures after an SSE stream begins.

Errors returned before streaming starts use a JSON envelope:

```json theme={null}
{
  "object": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "limit must be between 1 and 1000",
    "param": "limit",
    "request_id": "req_..."
  }
}
```

`param` and `request_id` are omitted when they are not available. A request ID may also appear in the `X-Request-Id` response header.

## HTTP status codes

| Status | Error type               | Meaning                                                                                        |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------------- |
| `401`  | `authentication_error`   | API key is missing, malformed, or unknown.                                                     |
| `402`  | `insufficient_credits`   | The account cannot reserve the maximum request cost.                                           |
| `403`  | `authentication_error`   | API key is revoked, expired, or lacks endpoint access.                                         |
| `409`  | `idempotency_error`      | The same idempotency key was reused with a different request body.                             |
| `409`  | `request_already_exists` | The same idempotent request already exists; response replay is not available.                  |
| `422`  | `invalid_request_error`  | Content type, JSON structure, field value, or request size is invalid.                         |
| `429`  | `concurrency_limit`      | The user-level or service-level concurrent request limit was reached.                          |
| `500`  | `internal_error`         | An internal dependency, upstream operation, protocol check, or settlement failed.              |
| `503`  | `service_unavailable`    | The endpoint or requested entity or contact type is not enabled or priced in this environment. |

The API intentionally redacts upstream response bodies, internal request IDs, and implementation details.

Not every status applies to every endpoint. In particular, Credit balance can return `401`, `403`, `500`, or `503`; it does not reserve credits and therefore does not return search billing or idempotency errors.

Contact Search returns errors before writing a success body. Upstream and response-protocol details are redacted, and a successful JSON result is not returned until billing settlement succeeds.

## Errors inside an SSE stream

Once the stream starts, later errors are delivered as an SSE `error` object while the HTTP status remains `200`. See [Streaming events](/api-reference/streaming-events#errors-after-streaming-starts).

## Retry guidance

| Condition                       | Guidance                                                                                                           |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `422`, `401`, `403`, `402`      | Fix the request, credential, or balance before retrying.                                                           |
| `429`                           | Wait before starting a new request. The API currently does not return `Retry-After`.                               |
| `500`, `503` before any result  | Retry with backoff and a new idempotency key only after deciding the original request will not be recovered.       |
| In-stream `error` after results | Preserve all IDs and contact lev8 support. The request may require reconciliation; do not automatically repeat it. |

<Tip>
  Log the HTTP status, error `type`, `request_id`, `X-Request-Id`, and `leads_search_id`. Never log the API key or the full request if it contains sensitive search criteria.
</Tip>