Rate Limits

SDK requests

Live API keys allow up to 120 requests per API key in any 60-second window. Sandbox test keys allow up to 60 requests per test key in any 60-second window. Every request uses one slot, including status checks and retry attempts.

This limit applies to normal SDK traffic across collections, payouts, status lookups, and invoices.

When a limit is reached

The operation returns a structured error with:

• reason: "RATE_LIMIT"
• A human-readable message with a suggested wait

Check retryable before building an automatic retry loop. Rate-limit errors normally become available after the suggested wait.

Use the global onError handler for one place to record the error. Operations returning a PaymentInstance also emit their normal "error" event, while Result operations return the error for parseError or parse_error.

import { createNylonPay } from '@nile-squad/nylonpay-ts';

const nylonpay = createNylonPay({
  apiKey: 'npk_test_...',
  apiSecret: 'nps_test_...',
  onError: (error) => {
    if (error.reason === 'RATE_LIMIT') {
      console.error('Slow down requests:', error.message);
    }
  },
});

When a rate limit error appears:

1. Stop sending requests for the suggested wait.
2. Retry only when the operation is safe to repeat.
3. Keep using the same reference when retrying a payment operation.
4. Reduce status-check frequency or concurrent work if the error repeats.

Do not parse the message text or rotate API keys to work around a limit.

New live accounts

New live accounts may have temporary payout restrictions while initial account checks complete. Collections and transaction status lookups remain available. Wait for the account restriction to clear before retrying a payout, or contact support if it continues.

Repeated failed payment attempts can also return a temporary RATE_LIMIT error. Correct the payment details before trying again.

See Also

• Error Handling, handle structured operation errors
• Configuration, set SDK request and polling options
• Security, protect API credentials and requests