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

# Rate limits and errors

> Per-endpoint rate limits and the API's error model.

## Rate limits

Rate limits are applied per API key, per minute. When you exceed a limit, the API returns `429`.

| Endpoint                                                  | Limit (per minute) |
| --------------------------------------------------------- | ------------------ |
| `GET /api/payouts/account-requirements`                   | 500                |
| `POST /api/payouts/account-requirements`                  | 500                |
| `GET /api/payouts/deposit-options`                        | 60                 |
| `GET /api/payouts/fee`                                    | 60                 |
| `GET /api/payouts/amount-limits`                          | 60                 |
| `GET /api/payouts/quote`                                  | 20                 |
| `POST /api/payouts/transfer`                              | 20                 |
| `POST /api/payouts/transfer/v2`                           | 20                 |
| `POST /api/payouts/transfer/v2/confirm-transfer`          | 20                 |
| `GET /api/payouts/transfer/{transfer_id}`                 | 30                 |
| `GET` / `POST` `/api/payouts/recipients`                  | 30                 |
| `GET` / `PATCH` / `DELETE` `/api/payouts/recipients/{id}` | 30                 |

Responses include `x-ratelimit-remaining` and `x-ratelimit-reset` headers so you can pace requests and back off before hitting the limit.

## Error format

All errors return a JSON body with a single human-readable `error` field.

```json theme={null}
{ "error": "Invalid or missing API key" }
```

## Status codes

| Code  | Meaning                                                                                                                                               |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Validation error — bad parameters, unsupported currency, or an amount outside your limits.                                                            |
| `401` | Missing, malformed, or revoked API key.                                                                                                               |
| `403` | Not permitted — recipient not owned by your account, transfer method not enabled, failed compliance screening, unverified wallet, or a disallowed IP. |
| `404` | Resource not found (for example, an unknown transfer or recipient).                                                                                   |
| `409` | Conflict — a duplicate `customer_uuid`, or a `tx_hash` already used by another transfer.                                                              |
| `429` | Rate limit exceeded. Retry after the window resets.                                                                                                   |
| `500` | Internal server error.                                                                                                                                |
| `503` | A compliance or wallet-verification service is unavailable. Retry after a short delay.                                                                |

<Tip>
  Treat `503` and `429` as retryable. Use the rate-limit headers to schedule retries, and add jitter to avoid retry storms.
</Tip>