Skip to main content
The Nmbr API limits how many requests you can make per minute. Every response tells you how much of your limit is left, and a request that goes over the limit returns 429 Too Many Requests without being processed. The same limits apply in sandbox and production.

​
Limits

Both limits cover the requests you make with your own access tokens. Requests made by the Nmbr Component are counted separately and do not count toward either limit.

​
How rate-limiting buckets work

A rate-limiting bucket is a counter. Each one counts your requests in a one-minute window. The window opens on your first request and the counter resets 60 seconds later. It is not aligned to the clock minute. Your allowance is per authenticated entity. Requests to partner endpoints count against your partner, and requests to company endpoints count against the company in the access token you used. Each company you serve gets its own 1,000 requests per minute, so a busy company can’t exhaust another company’s allowance. The reveal bucket is additional. A call to a /reveal endpoint counts against both the reveal bucket and the API requests bucket. Reveal endpoints return sensitive values such as a full Social Insurance Number, so they carry a tighter limit of their own. Read one record at a time and cache what you need rather than revealing a list of employees in a loop. Nmbr Component traffic does not count toward your API rate limits. Requests the Component makes for your users go into a rate-limiting bucket of their own, separate from the buckets above. A user working in the Component never consumes the allowance your own integration is spending.

​
Rate limit headers

Every response carries your standing in the rate-limiting bucket: A 429 response adds two more: When more than one limit applies to an endpoint, the headers describe the rate-limiting bucket you are closest to exhausting.

​
Over the limit

Response
Wait Retry-After seconds, then retry. A 429 means the request never reached the API, so nothing was created, updated, or deleted. If the request carried an X-Idempotency-Key, the key was not consumed and you can retry with the same one. See Idempotency.

​
Staying under the limit

  • Use the bulk and batch endpoints to write many entities in one request instead of one request per entity.
  • Use expand to pull related resources into a single response instead of following each stub with another request.
  • Back off using Retry-After instead of retrying immediately. Retrying in a tight loop keeps you over the limit and delays your own recovery.