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

# CoinVoyage API rate limits, 429 responses, and retry behavior

> Understand CoinVoyage API rate limits, how to handle 429 Too Many Requests responses, and recommended retry and backoff behavior for production integrations.

CoinVoyage applies rate limits to keep payment flows reliable during traffic spikes, retries, and abusive request patterns. Limits vary by endpoint and credential type.

## 429 responses

When a request exceeds a limit, CoinVoyage returns `429 Too Many Requests`:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: <seconds>
```

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again later.",
  "code": 429
}
```

If `Retry-After` is present, wait at least that many seconds before retrying.

## Retry guidance

* Respect `Retry-After` instead of retrying immediately.
* Add jitter when multiple workers or browser tabs may retry the same operation.
* Use bounded exponential backoff for network failures and `5xx` responses.
* Retry reads more freely than create or mutation requests.
* Keep fulfillment and reconciliation idempotent by CoinVoyage order ID.

<Tip>
  Use webhooks for payment state changes. Polling is useful for dashboard views and reconciliation jobs, but webhooks should be the primary completion signal.
</Tip>