Skip to main content

​
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): 
BASE_URL=${PEPAY_API_URL}

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

​
Response

Representative 429 response body: 
{
  "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