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

# Errors

> The exact status codes the adapter reacts to, and how it reacts — retries, skips, and failures.

Return standard HTTP status codes. HunterAI's behaviour for each is fixed and listed below.

## Error body shape

On any error, return a JSON body with an `error` string. HunterAI reads it into the failure
detail it records for the sync:

```json theme={null}
{ "error": "invalid token" }
```

The body is optional — HunterAI falls back to the status code if it is absent or not JSON —
but a clear message makes failures easy to diagnose. Only the first 300 characters are kept.

## Status codes

| Status                          | HunterAI's reaction                                                                                                                                                                         |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`                           | Success. The `data` page is ingested.                                                                                                                                                       |
| `401`                           | **Auth failure, no retry.** The entity fails immediately. Because the token is used for every entity, all entities fail the same way and the sync is reported failed.                       |
| `404`                           | **Endpoint not implemented.** On an [optional](/endpoints/events) endpoint → skipped cleanly (0 records, still success). On a [required](/endpoints/pipelines) endpoint → the entity fails. |
| `429`                           | **Rate limited, retried.** Honours `Retry-After`, otherwise backs off exponentially. Up to 5 retries, then the entity fails. See [Rate limits](/rate-limits).                               |
| `5xx`                           | **Server error, retried.** Exponential backoff, up to 5 retries, then the entity fails.                                                                                                     |
| other `4xx` (e.g. `400`, `403`) | **Hard failure, no retry.** The entity fails immediately.                                                                                                                                   |

<Note>
  "The entity fails" means that one entity (e.g. `/leads`) is marked failed for the run;
  entities that already committed stay committed. See
  [Partial success](/concepts/how-sync-works#partial-success).
</Note>

## 401 Unauthorized

```json theme={null}
{ "error": "invalid or expired token" }
```

* No retry — HunterAI stops the entity the instant it sees `401`.
* Nothing from an unauthenticated call is ingested.
* Every entity in the run hits the same `401`, so the whole sync ends *failed*.

<Warning>
  **What the business owner sees:** the connection's sync is marked *failed* with an
  authentication error. The fix is to update the token on the connection (see
  [Authentication → Rotating](/authentication#rotating-the-token)) and re-run the sync.
</Warning>

## 404 Not Found

`404` is how you declare an **optional** endpoint unimplemented.

<CodeGroup>
  ```json Optional endpoint (skipped) theme={null}
  // GET /calls → 404
  { "error": "calls not implemented" }
  // Result: calls entity = success, 0 records. Sync still succeeds.
  ```

  ```json Required endpoint (fails) theme={null}
  // GET /pipelines → 404
  { "error": "not found" }
  // Result: pipelines + stages entities fail. Sync reported failed.
  ```
</CodeGroup>

<Warning>
  Do **not** return `404` for an implemented endpoint that simply has no data — return
  `200` with `{ "data": [], "has_more": false }` instead. A `404` on a required endpoint is
  read as "not implemented" and fails the entity.
</Warning>

## 429 and 5xx errors

Both are treated as transient and retried up to **5 times** before the entity fails.

* **`429`** — HunterAI waits for the larger of your `Retry-After` header (seconds, floored
  to 1s) and an exponential backoff (`1, 2, 4, 8, 16` s).
* **`5xx`** — HunterAI backs off exponentially (`1, 2, 4, 8, 16` s) and retries.

If the endpoint is still failing after the retries, that entity is marked failed and the
rest of the sync continues.

## Other 4xx — hard failure

`400`, `403`, `422`, and any other 4xx that is not `401`, `404`, or `429` fail the entity
**immediately with no retry**. Reserve these for genuine client errors; do not use them for
throttling (use `429`) or transient issues (use `5xx`).