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

# Errors & rate limits

> Error shapes, status codes and rate-limit behaviour.

## Error shape

Developer (`/v1/*`) endpoints return errors in a typed envelope:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "message": "payout_address must be a 0x EVM address"
  }
}
```

## Status codes

| Status | Meaning                                         | What to do                                         |
| ------ | ----------------------------------------------- | -------------------------------------------------- |
| `200`  | Success                                         | —                                                  |
| `400`  | Invalid request (bad JSON or failed validation) | Fix the request body                               |
| `401`  | Missing or invalid API key                      | Check the `Authorization` header                   |
| `404`  | Resource not found                              | Verify the id/path                                 |
| `429`  | Rate limited                                    | Back off and retry                                 |
| `5xx`  | Server error                                    | Retry with backoff; contact support if it persists |

## Common error types

* `authentication_error` — the key is missing, invalid or revoked.
* `invalid_request_error` — a field failed validation; `message` names the first
  problem.

## Rate limits

Endpoints are rate-limited per key (and per IP as a floor). A limited request
returns `429`. Use exponential backoff with jitter, and design writes to be safe
to retry — pass a stable `reference` on payments so a retry doesn't create a
duplicate you can't recognise.