Rate limits

The OrcaRail API limits how many requests one client IP address can send in a time window. This protects merchants and their customers from abuse such as brute-force sign-in attempts, mass password-reset emails, and checkout spam.

Default limit

Every endpoint allows up to 600 requests per minute per IP address. Normal server-to-server integrations (payment intents, subscriptions, webhooks configuration, rates) stay well below this.

Stricter limits on sensitive endpoints

Endpoints that send email, check a secret, or can be called without authentication have lower per-IP limits:

Endpoint group	Limit per IP
Password reset request (POST /api/v1/auth/forgot/password)	3 per 15 minutes
Email sign-in (POST /api/v1/auth/email/login)	10 per 5 minutes
Sign-up, sign-in codes, password reset	5 per 15 minutes
Confirmation email resend (POST /api/v1/auth/email/confirm/resend)	3 per 15 minutes
Code verification and POST /api/v1/api-keys/test	10 per 15 minutes
Google sign-in, payer wallet challenge and verify	20 per 5 minutes
Public checkout (POST /api/v1/widgets/{id}/checkout, POST /api/v1/pay/{slug}/confirm, POST /api/v1/pay/{slug}/cancel)	30 per minute

Some auth endpoints also apply per-email protection:

• A password reset email is sent at most once every 5 minutes per address. The endpoint always returns 204 and never reveals whether an account exists.
• After 10 failed password sign-ins, that email is locked for 15 minutes (429 with errors.email = "tooManyLoginAttempts" and canRetryAt).
• Each address receives a limited number of auth emails per 24 hours, whatever IP the requests come from: 5 confirmation resends, 5 password reset emails, 10 sign-in codes and 10 sign-up codes. Over the cap, resend and password reset still return 204 but send nothing; code requests return 429 with errors.email = "tooManyEmails" and canRetryAt.
• Each password reset link works once. After the password changes, older links return 422 with errors.hash = "invalidHash".

The 429 response

When a limit is exceeded the API responds with 429 Too Many Requests and a Retry-After header giving the number of seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 742

{ "statusCode": 429, "message": "ThrottlerException: Too Many Requests" }

Successful responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.

Handling 429 in your integration

• Wait at least Retry-After seconds before retrying; do not retry in a tight loop.
• Use exponential backoff with jitter for automated retries.
• Cache responses that rarely change, such as networks and tokens and rates.

reCAPTCHA on dashboard sign-in

The dashboard sign-in, sign-up, confirmation-resend and password-reset forms are protected by Google reCAPTCHA v3. The API expects a token in the x-recaptcha-token header on those endpoints and responds 400 with errors.recaptcha = "recaptchaFailed" if verification fails. These endpoints are for the dashboard only; server-to-server integrations authenticate with API keys and are not affected.