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

# Rate Limits

> How to handle rate limiting and safe retries.

## Overview

Rate limits protect API reliability across merchant, commerce, and public surfaces. When you hit a limit, the API responds with `429`.

Rate limits may vary by endpoint and auth mode. Design your integration so **bursty retries** don’t turn into a thundering herd.

## Authentication

Rate limits apply regardless of auth mode:

* Merchant: `x-api-key`
* Commerce: `x-commerce-api-key`
* Payor/session: `x-session-token` + `x-signature`

## Request

Example request (any endpoint):

```bash theme={null}
BASE_URL=${PEPAY_API_URL}

curl "$BASE_URL/api/v1/invoices?limit=1" \
  -H "x-api-key: sk_live_..."
```

## Response

Representative `429` response body:

```json theme={null}
{
  "success": false,
  "message": "Too many requests from this IP. Please try again later.",
  "error_code": "RATE_LIMIT_EXCEEDED",
  "retry_after": "15 minutes"
}
```

## Errors

* `429` rate limit exceeded (respect `Retry-After` header when present; use `retry_after` as a hint)
* `5xx` transient upstream errors (retry with backoff where safe)

## Examples

Best practices:

* Respect `Retry-After` when present.
* Use exponential backoff with jitter for retries.
* Ensure writes are idempotent (use `Idempotency-Key`).

SDK behavior:

* `pepay` includes safe retry behavior and idempotency key support by default.

Next: [Pagination](/api-spec/pagination)