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.
| Response | Meaning | Retry? |
|---|---|---|
403 | Quota used up | No |
429 | Rate limit exceeded | Yes, after Retry-After |
503 | Service busy | Yes, 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:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Quota for the current period |
X-RateLimit-Remaining | Requests left in the period |
X-RateLimit-Reset | Unix 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
403 quota_exceededStop 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
429 and 503- Read the
Retry-Afterheader. It gives the number of seconds to wait. - 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.
- If the retry fails, wait longer before each next attempt (exponential backoff).
- 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.
Updated about 9 hours ago
