Skip to content

Rate limits

What the API does when you send too much, and how to back off.

Sandbox: test money only. No request moves real money.

Requests past the limit are refused with 429 and the code rate_limited. The response carries a Retry-After header with the number of seconds to wait. Some 503 responses carry it too. A successful response says how much of your budget is left, so you can slow down before you are refused.

Rate limit headers

Each successful response, and each 429, carries two headers, in the form of draft-ietf-httpapi-ratelimit-headers-11, an Internet-Draft that is not yet an RFC. A request draws on one or more buckets, and both headers name each bucket it drew on:

HeaderWhat it holds
Ratelimit policyRateLimit-PolicyEach bucket as "<bucket>";q=<quota>;w=<window seconds>: how many requests the window allows.
RatelimitRateLimitEach bucket as "<bucket>";r=<requests remaining>;t=<seconds until the quota is full again>. The remaining count is never negative.

The buckets are orders, quotes, quotes_daily, reads, webhooks, lookups, lookups_org and lookups_daily. A recipient lookup draws on the last three alone. An order without a quote_id (the minimal order or a direct order) makes its own quote, so it draws on quotes and quotes_daily as well as orders, a replay of it included. The contract lists every bucket's quota and window in x-nb-rate-limits, but Nasfam can set quotes_daily and lookups_daily for one organisation: read your own figures from RateLimit-Policy instead of hard-coding them.

A bucket that cannot be read at once because of contention is answered with 429 too, never waited on. A 503 service_unavailable with Retry-After means the rate limiter could not answer and the request was not processed.

Code for Rate limit headers
A limited request
JSON
429 Too Many RequestsSynthetic sandbox data
{  "type": "about:blank",  "title": "Too many requests",  "status": 429,  "code": "rate_limited",  "category": "rate_limit",  "detail": "Too many requests. Retry after the time in Retry-After.",  "param": null,  "request_id": "req_01K7SAMP000000000000000090"}

Backing off

  • Wait at least Retry-After seconds, then send the request again. For a request that changes your balance, use the same Idempotency-Key.
  • Watch RateLimit: when the requests remaining in a bucket near 0, slow that kind of request down before it is refused.
  • Add jitter when many workers share one key, so they do not all return at the same second.
  • Prefer webhooks to polling: you are told when an order changes, instead of asking.
  • Read lists with limit up to 100 instead of fetching objects one by one.
Code for Backing off
GET /v1/ordersSandbox, test key
// npm install axiosimport axios from 'axios';try {  const { status, data: orders } = await axios.get(    'https://sandbox-api.nasfampay.com/v1/orders',    {      params: { reference: 'TEST-0001', limit: 10 },      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,      },    },  );  console.log(status, orders);} catch (error) {  if (!axios.isAxiosError(error) || !error.response) throw error;  const problem = error.response.data;  throw new Error(`${problem.status} ${problem.code}: ${problem.title} (request ${problem.request_id})`);}

Other limits that look like rate limits

queue_limit, also a 429, means the account has max_queued orders in progress already; it is per account, not per second, and clears as orders finish. capacity_exhausted means delivery capacity is used up for now.

Common mistakes

  • Retrying at once, in a loop. A refused request sent again immediately is refused again. Wait for Retry-After.
  • Polling every order on a timer. Subscribe to the order events and read an order only when one arrives.