Quota & Rate Limits

How many requests your API key can make, and how to handle the responses when you reach a limit.

Overview

Your API key has two limits for each API:

  • Quota: the total number of requests per day, or for the full trial.
  • Rate limit: the number of requests per second.

The limits depend on your plan and apply per API. Requests to NL Organizations do not count towards your limits for Compliance Screening, for example. All applications that use the same key share its limits.

When the service is under heavy load, the API can also ask you to slow down for a short time, even if your key is within its limits.

ResponseMeaningRetry?
403Quota used upNo
429Rate limit exceededYes, after Retry-After
503Service busyYes, after Retry-After

All errors use the JSON:API error format. Use the code field to tell the cases apart.


Quota

The quota sets how many requests your key can make to one API in total:

  • Paid plans: a daily quota per API. It renews 24 hours after the first request of the current period.
  • Trial keys: a fixed quota per API for the full trial. It does not renew.

Every request that passes the rate limit counts towards the quota. This includes requests that return an error, such as 404.

When the quota is used up, the API returns 403 Forbidden with the code quota_exceeded. There is no Retry-After header.

HTTP/1.1 403 Forbidden
Content-Type: application/vnd.api+json
{
  "errors": [
    {
      "status": "403",
      "code": "quota_exceeded",
      "title": "Quota exceeded",
      "detail": "The request quota for ...",
      "links": { "type": "..." }
    }
  ]
}

The links.type field links to this page.

Do not retry this response automatically. Every retry fails until the quota renews.

A 403 with another code means something else, usually that your key has no access to this API. See API Keys & Access.

Check your remaining quota

Successful responses include three headers about the quota of your key for the API you called:

HeaderMeaning
X-RateLimit-LimitQuota for the current period
X-RateLimit-RemainingRequests left in the period
X-RateLimit-ResetUnix time when the quota renews

Despite their names, these headers show the quota, not the per-second rate limit. Error responses do not include them.

Use X-RateLimit-Remaining to slow down or alert before the quota runs out.


Rate limit

The rate limit sets how many requests your key can make to one API per second.

When you exceed it, the API returns 429 Too Many Requests. The Retry-After header gives the number of seconds to wait before you retry.

HTTP/1.1 429 Too Many Requests
Content-Type: application/vnd.api+json
Retry-After: 2
{
  "errors": [
    {
      "status": "429",
      "code": "rate_limit_exceeded",
      "title": "Rate limit exceeded",
      "detail": "Too many requests per second ...",
      "links": { "type": "..." }
    }
  ]
}

A request rejected with 429 does not count towards your quota.


Service busy

To stay fast and available for everyone, the service protects itself against overload. When it is too busy to handle your request, the API returns 503 Service Unavailable with a Retry-After header. This can happen even when your key is within its own limits.

HTTP/1.1 503 Service Unavailable
Content-Type: application/vnd.api+json
Retry-After: 5
{
  "errors": [
    {
      "status": "503",
      "code": "capacity_exceeded",
      "title": "Temporarily at capacity",
      "detail": "The service is busy. ...",
      "links": { "type": "..." }
    }
  ]
}

A 503 with the title Maintenance Mode means planned maintenance. It has a longer Retry-After. Check our status page for details.

Handle every 503 the same way: wait for the number of seconds in Retry-After, then retry.


Handle limits in your integration

Stop on 403 quota_exceeded

Stop sending requests to that API until the time in the last X-RateLimit-Reset header you received. To raise your quota, contact us.

Retry 429 and 503

  1. Read the Retry-After header. It gives the number of seconds to wait.
  2. Wait at least that long, plus a small random delay (jitter), then retry. The random delay stops many clients from retrying at the same moment.
  3. If the retry fails, wait longer before each next attempt (exponential backoff).
  4. Stop after a fixed number of attempts and report the error.

Always use the value of the header. Do not hard-code a waiting time, because the value can change.

Stay under the limits

  • Spread requests evenly instead of sending them in bursts.
  • Limit the number of parallel requests per key.
  • Cache data that does not change often, such as organization profiles.
  • Avoid polling. To track changes, use NL Monitoring or Compliance Monitoring.

Troubleshooting

403 quota_exceeded

The quota of your key for this API is used up. Do not retry. Wait until it renews, or contact us to upgrade.

403 with another code

Your key has no access to this API. Check that you use the right key. See API Keys & Access.

429 rate_limit_exceeded

Your key sent too many requests per second. Wait for Retry-After, retry, and lower your request rate.

503 capacity_exceeded

The service is busy. Wait for Retry-After, then retry with backoff.

503 Maintenance Mode

Planned maintenance. Wait for Retry-After and check our status page.


Your limits

Your rate limit and quota depend on your plan. To find out your limits or to request higher ones, contact Company.info.


Did this page help you?