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

# Errors & Status Codes

> What each status means and how to handle it.

Errors return a JSON body with an `error` message:

```json theme={null}
{ "error": "Human-readable error message." }
```

## Status codes

| Status | Meaning                                                                                                                                                                                                                                                                                                                          | What to do                                                                                          |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `200`  | Success: the audit verdict is in the body (or, with `async=true`, a `{ "status": ... }` progress body).                                                                                                                                                                                                                          | Read `audit.isSafe`; if the body has `status`, keep polling.                                        |
| `400`  | Invalid request: unknown `chain` or malformed `address`.                                                                                                                                                                                                                                                                         | Fix the parameters; don't retry as-is.                                                              |
| `401`  | Missing or invalid API key.                                                                                                                                                                                                                                                                                                      | Check the `X-Auth-Key` header and the key's status.                                                 |
| `402`  | No active subscription, or your credit allowance is exhausted.                                                                                                                                                                                                                                                                   | See the `action` field (below) and top up or subscribe.                                             |
| `404`  | The contract is not tradable yet (no liquidity pool).                                                                                                                                                                                                                                                                            | Retry once a pool exists (see below).                                                               |
| `429`  | Spend cap reached. On `/audit-contract` the body carries `cap_usd` and `used_usd` (no `action`). On the subscribe endpoints (`POST /api/subscriptions`, `import-history`) a projected bulk cost that would cross the cap returns `action: "raise_cap"` with `required_credits` / `remaining_credits`, and nothing is subscribed. | Raise the cap in the dashboard / with your account manager; this is not a `5xx`, don't blind-retry. |
| `5xx`  | Temporary server error.                                                                                                                                                                                                                                                                                                          | Retry with exponential backoff.                                                                     |

## Not tradable yet (`404`)

Only tradable contracts are audited. If no liquidity pool exists for the contract yet, the response is a `404` with a machine-readable reason rather than a generic error:

```json theme={null}
{
  "audit": null,
  "reason": "no_liquidity_pool",
  "message": "No liquidity pool found for this token yet — only tradable contracts are audited. Retry once a pool has been created."
}
```

Treat this as "not ready yet", not a hard failure. Retry once the contract has a pool.

## Handling `402`

A `402` includes an `action` hint for what to do next:

```json theme={null}
{ "error": "Monthly credit limit reached", "action": "upgrade" }
```

| `action`                                | Meaning                                                                                       |
| --------------------------------------- | --------------------------------------------------------------------------------------------- |
| `subscribe`                             | No plan yet: choose one on the [pricing page](https://www.serializedaudit.io/portal/plans).   |
| `add_payment`                           | A payment failed: update your card in the dashboard.                                          |
| `resubscribe`                           | The subscription ended: start a new one.                                                      |
| `upgrade`                               | Out of credits for the period: upgrade or enable pay-as-you-go.                               |
| `wait`                                  | A time-based limit is active (e.g. daily trial cap): retry after the `resets_at` in the body. |
| `verify_payment` / `payment_processing` | Pay-as-you-go collection in progress: no action, retry shortly.                               |
| `raise_cap`                             | Your own spending cap was hit: raise it in the dashboard.                                     |

Denial bodies may carry extra context fields depending on the wall (`resets_at`, `daily_limit`, `grace_usd`, `current_period_end`, `subscription_status`). Treat the shape as open.

<Tip>
  Treat `400` and `401` as permanent (fix the request), and `5xx` as transient (retry). For `402` and `429`, surface the response to whoever manages billing; neither clears on a blind retry.
</Tip>