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

# Errors

> Every error is JSON with a stable machine code. Branch on `error`, never on `message`.

Every error response across the API — from a 400 to a 500 — is JSON with the **same
envelope**, so a client that `.json()`s every response never breaks on an error.

```json theme={"theme":"github-dark"}
{ "error": "unknown_asset", "message": "asset 'FOO' is not in the tracked universe", "asset": "FOO" }
```

<Note>
  Branch on the stable **`error`** code, never on the human-readable `message` (which may
  be reworded at any time). `asset` is present only on asset-scoped errors.
</Note>

## Status codes

The HTTP status tells you the class; the `error` code tells you the specifics.

| Status | Meaning |
| - | - |
| `2xx` | Success. |
| `400` | Bad request — malformed input. |
| `404` | Not found — unknown asset or endpoint. |
| `429` | Rate limit exceeded (see [Rate limits](/guides/rate-limits)). |
| `5xx` | Unexpected server error — safe to retry with backoff. |

## Error codes

| `error` | Status | When |
| - | - | - |
| `unknown_asset` | 404 | The symbol/mint is not in the tracked universe. Carries `asset`. |
| `not_found` | 404 | No such endpoint — see [`GET /`](https://api.pegana.xyz/) or [`/openapi.json`](https://api.pegana.xyz/openapi.json). |
| `invalid_body` | 400 | The request body failed validation. |
| `rate_limited` | 429 | Per-IP limit exceeded; a `Retry-After` header tells you when to retry. |
| `internal` | 500 | Unexpected server error. Retry with backoff; if it persists, quote the `x-request-id`. |

## Debugging with `x-request-id`

**Every response** (success or error) carries an **`x-request-id`** header. When something
looks wrong, grab it and include it in your report — it lets us trace the exact request.

```bash theme={"theme":"github-dark"}
curl -sS -D - -o /dev/null https://api.pegana.xyz/v1/stats | grep -i x-request-id
# x-request-id: 6f6b2f0e-9a1c-4c2e-8b7a-3d4e5f6a7b8c
```

If you send your own `x-request-id` header, we echo it back so the id survives across your
own hops.


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