Rate Limits

SDK requests

The SDK allows up to 120 requests per API 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. Other traffic protections can also return RATE_LIMIT before the normal per-key allowance is reached.

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.

The exact account-protection thresholds are not part of the merchant contract. Repeated failed payment attempts can also receive a temporary rate_limit error. Correct the payment details before trying again.

Request limits and transaction limits

The SDK request limit controls how often your integration can call the API. It does not change the maximum amount allowed in one transaction. Per-transaction amount limits are separate and may vary by account and operation. An approved increase to a transaction amount cap does not increase request capacity.

See Also

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