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

# Handling Errors

> Find out why a request failed and how to retry it.

## Error response

HTTP `2xx` means the request was accepted or returned successfully, not that a Job succeeded. `4xx` indicates an input, authentication, access, state or limit problem. `5xx` indicates a service or execution failure.

```http theme={null}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
X-Request-Id: req_3f8b2c1e
```

```json theme={null}
{
  "error_code": "validation_error",
  "detail": "At least one field is required",
  "param": "body.fields",
  "retryable": false,
  "request_id": "req_3f8b2c1e"
}
```

| Field or header | Meaning |
| - | - |
| `error_code` | Code to use when handling the error. See [Error codes](#error-codes). |
| `detail` | Human-readable explanation. Its wording can change. Use `error_code`, not this text, to choose how to handle the error. |
| `param` | Invalid parameter path, such as `body.fields`. Null when not applicable. |
| `retryable` | Whether the same request can succeed on retry. |
| `request_id` | ID matching the `X-Request-Id` response header. Include it in support requests. |
| `Retry-After` | Seconds to wait before retrying a retryable response. |

Job and item failures include an `error` object with `error_code` and `detail`. Check the Job's `status` even when the request returns HTTP `200`: the Job can still have `status: "failed"`.

## Error codes

| Code | HTTP status | Retryable | Meaning | Action |
| - | -: | - | - | - |
| `unauthenticated` | 401 | `false` | Authentication is missing or invalid. | Supply a valid API key or refresh your access token. |
| `insufficient_credits` | 402 | `false` | Billing or credit limits prevent this request. | Check your subscription, balance and team spending limits before retrying. |
| `validation_error` | 422 | `false` | Request parameters failed validation. | Correct the parameters named in `param` and `detail`. |
| `rate_limited` | 429 | `true` | A request or concurrency limit was reached. | Follow `Retry-After` and reduce request concurrency. |
| `not_found` | 404 | `false` | The resource does not exist or is not visible to this caller. | Check the ID and your organization and team context. |
| `forbidden` | 403 | `false` | This caller lacks permission for the action. | Check permissions and organization or team membership. |
| `idempotency_key_reused` | 409 | `false` | The key was already used with a different request. | Keep the original body for a retry; use a new key for different work. |
| `invalid_cursor` | 400 | `false` | The cursor is invalid or does not match this request. | Restart pagination without a cursor. Keep the source, filters and page size unchanged between pages. |
| `limit_exceeded` | 422 | `false` | The request exceeds a supported limit. | Reduce the requested size or wait for capacity, as `detail` directs. |
| `job_not_finished` | 409 | `true` | This action requires a finished Job. | Poll until the Job succeeds, fails or is canceled, then try again. |
| `items_not_available` | 409 | `false` | Per-record items are unavailable or cannot be safely matched to their inputs. | If the Job is running, wait for it to finish. Otherwise check `result` for files or contact support; do not restart paid research automatically. |
| `request_in_progress` | 409 | `true` | A matching start request is still being registered. | Follow `Retry-After`, then repeat the unchanged request with the same key. |
| `list_not_ready` | 409 | `true` | The list is not ready for this action. | Wait for `ready`. If list creation failed, correct its source before creating a replacement. |
| `unsupported_file` | 422 | `false` | The file format is unsupported. | Use a format accepted by the Files API. |
| `invalid_upload` | 422 | `false` | The contents, declared size or upload ticket failed validation. | Check the file and its size; request a fresh upload ticket if needed. |
| `file_too_large` | 413 | `false` | The file exceeds the applicable byte limit. | Split or reduce the file. Check the limit for the upload method you use. |
| `entity_type_mismatch` | 422 | `false` | The source has a different people or company type. | Use a source matching the entity type requested by this action. |
| `export_source_changed` | 409 | `false` | The export source changed since your first request. | Start a new export with a new key after the source is stable. |
| `job_execution_changed` | 409 | `false` | The Job changed execution while it was being read. | Read the Job again and restart item pagination without a cursor. |
| `item_failed` | 422 | `false` | One input record could not be processed. | Inspect the item's `error.detail`; deliberately retry only affected records with a new key. |
| `job_failed` | 500 | `false` | The Job ended with an execution error. | Inspect its error and available successful items before starting replacement work. |
| `unavailable` | 503 | `true` | The service is temporarily unavailable. | Follow `Retry-After` and retry unchanged. Keep the same key on a start request. |
| `internal_error` | 500 | `true` | The service encountered an unexpected error. | Follow `Retry-After`; keep the same start key. Contact support with the request ID if it persists. |
| `timed_out` | 504 | `false` | Execution reached a timeout. | Inspect the Job and saved results before starting replacement work. Expiring `wait_seconds` alone returns 202, not this error. |
| `aborted` | 409 | `false` | The Job was terminated before completion. | Inspect its status and available results before starting replacement work. |

## Retry rules

* Fix invalid parameters before retrying `validation_error`.
* Replace or rotate the key for `unauthenticated`; check permissions for `forbidden`.
* Reuse the same `Idempotency-Key` and unchanged body when a start request fails with a retryable error.
* Use a new key for a deliberately different request after `idempotency_key_reused`.
* Follow `Retry-After` when `retryable` is true. If retries continue to fail, contact support with the request ID.
* For `items_not_available`, wait if the Job is still running. If it has finished, check its `result` for files or contact support. Do not restart paid research automatically.

For older route errors, see [Legacy Errors](https://docs.sixtyfour.ai/api-reference/legacy/errors.md).


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