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

# Error codes

> HTTP status codes and JSON error shapes returned by the API.

This page covers the **x402 API**.  V2 API errors are listed inline
on each endpoint page (see [POST /v2/check-address](/api-reference/v2-check-address)
and [POST /v2/screen](/api-reference/v2-screen)).

All error responses follow the same JSON shape:

```json theme={null}
{
  "error": {
    "code":    "<machine-readable slug>",
    "message": "<human-readable explanation>"
  }
}
```

## 402 — Payment Required

The expected response on every paid endpoint until you supply a
valid `X-PAYMENT` header.  See [Authentication](/authentication/x402)
for how to read the `payment-required` quote.

| `code`              | Meaning                                                    |
| ------------------- | ---------------------------------------------------------- |
| `payment_required`  | First-call default — no proof was sent                     |
| `payment_invalid`   | `X-PAYMENT` was present but failed signature verification  |
| `payment_expired`   | The signed quote's `validBefore` is in the past            |
| `payment_replayed`  | Same `(payer, nonce)` already settled — sign a fresh nonce |
| `payment_underpaid` | Signed amount less than the quote's `amount`               |

The `payment-required` header always accompanies a 402 with a
**fresh** quote, so a client can re-sign without re-fetching.

## 400 — Bad Request

| `code`              | Meaning                                                                                            |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| `chain_unsupported` | `{chain}` is not in the [networks](/reference/networks) list                                       |
| `address_invalid`   | `{address}` doesn't match the expected format for the chain (EVM `0x` + 40 hex, TRON base58, etc.) |
| `body_invalid`      | Reserved (no current paid endpoint takes a body)                                                   |

## 429 — Rate limited

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: 60 per 1 minute"
  }
}
```

60 paid calls/minute per IP.  Defense in depth on top of the cost
of x402 itself.  Behind a NAT?  We're working on per-payer rate-
limiting; for now, contact us if it's blocking a legitimate workload.

## 500 — Aegis-side failure (post-payment)

```json theme={null}
{
  "error": {
    "code": "aegis_internal_error",
    "message": "..."
  }
}
```

Payment was settled but our backend errored.  Rare; logged to our
audit channel.  We don't auto-refund — but if you see a `500` after
a confirmed `tx_hash` on Basescan, [contact support](mailto:support@aegis-kyt.com)
with the `tx_hash` and we'll credit you back.

## 502 — Aegis backend unavailable

```json theme={null}
{ "error": { "code": "backend_unavailable", "message": "..." } }
```

The Aegis engine (or a required upstream RPC) was temporarily
unreachable after payment.  On the V2 ledger path this auto-refunds;
on x402 see the `500` note above for the credit-back flow.