Documentation / Reference

Rate limits

PayInference uses fixed one-minute windows. Limits are deployment settings, so treat values returned in 429 responses as authoritative.

Authenticated API traffic#

The default is 2,000 requests per minute per API key or dashboard session (RATE_LIMIT_PER_MINUTE). All endpoints called by that principal share the window.

json

{ "error": "rate_limited", "limit_per_minute": 2000 }

On POST /v1/decision, take the configured local fallback instead of waiting for the next window. Queue non-critical outcome and read requests, then retry with backoff.

Use separate least-privilege keys per service. If sustained legitimate traffic approaches the limit, raise the deployment setting before launch.

Public endpoints#

Login and registration default to 10 attempts per minute per source IP (AUTH_RATE_LIMIT_PER_MINUTE).
Provider webhooks default to 600 requests per minute per source IP and per provider/merchant route (WEBHOOK_RATE_LIMIT_PER_MINUTE).

Public endpoint limits run before database work. Webhook signatures remain the authenticity control.

Behind a reverse proxy, set TRUST_PROXY_HOPS to the exact trusted hop count so source-IP limits do not group all traffic under the proxy address. The proxy must overwrite, not append untrusted client-supplied forwarding headers.

Availability behavior#

Rate limiting uses Redis and fails open if Redis is unavailable. Payment and webhook delivery stay available, but abuse protection is degraded; operators should alert on Redis failures.

The API does not currently send Retry-After. For a fixed window, retry after the next minute boundary with jitter.