How to handle 429 Too Many Requests and build an integration that stays reliable under load.
Rate Limits
Every NikoHealth API endpoint returns 429 Too Many Requests when requests come in faster than its limit.
Endpoints | Limit |
Insurance eligibility: | 25 requests per second |
All other endpoints | 300 requests per second |
💡 Eligibility has a much lower limit. If you run eligibility checks in bulk (for example, a nightly check of upcoming orders), throttle those requests to 25 per second separately from the rest of your traffic.
Even within these limits, design your integration to handle a 429 at any time.
💡 Planning a large initial data load or another high-volume job? Contact support@nikohealth.com before you start.
Handling a 429
When you receive a 429:
Stop sending requests to that endpoint briefly.
Retry the same request after a delay.
Increase the delay with each consecutive 429 (exponential backoff), and add a little randomness (jitter) so parallel workers don’t retry at the same moment.
Give up after a reasonable number of attempts (e.g. 5) and log the failure for follow-up.
Example Backoff Schedule
Attempt | Wait before retrying |
1 | 1 second + jitter |
2 | 2 seconds + jitter |
3 | 4 seconds + jitter |
4 | 8 seconds + jitter |
5 | 16 seconds + jitter, then stop |
Example (Node.js)
async function callWithRetry(fn, maxAttempts = 5) {
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
const res = await fn();
if (res.status !== 429 && res.status < 500) return res;
if (attempt === maxAttempts) return res;
const delayMs = Math.pow(2, attempt - 1) * 1000 + Math.random() * 250;
await new Promise(r => setTimeout(r, delayMs));
}
}
What to Retry
Response | Retry? | Notes |
429 | ✅ With backoff |
|
5xx | ✅ With backoff | Temporary server-side problem |
Network timeout or connection error | ✅ With backoff | See Safe Retries below |
401 | Once, after getting a new token | |
400, 403, 404 | ❌ | Fix the request; retrying returns the same result |
Safe Retries
GET, PUT, and DELETE requests can usually be retried safely.
Be careful retrying POST requests that create records, such as patients, orders, insurances, payments, and documents. If the first attempt actually succeeded but the response was lost (for example, a timeout), a retry can create a duplicate.
Before retrying a create after a timeout:
Search first. For example, look up the patient by name and date of birth, or the order by patient and start date.
Store external references. Save your own system’s ID in a custom field so you can find the record if you need to.
Reduce Your Request Volume
The best way to avoid 429s is to make fewer requests:
Use webhooks instead of polling for changes. See Webhooks API.
Use modified-date filters to fetch only what changed. See Pagination, Filtering, and Syncing Changes.
Use larger page sizes instead of many small pages.
Cache reference data (locations, payers, products, document types) instead of looking it up on every request.
Reuse your access token for its full 20-minute lifetime instead of requesting a new one per call.
Use batch endpoints where available, for example
POST /v1/inventory-items/batch/receive,PUT /v1/inventory-items/batch/move,POST /v1/tasks/complete, andPOST /v1/faxes/inbox/trash.Spread out bulk jobs. For large imports, throttle your own request rate and run them outside peak business hours.
Monitoring
Log every 429 and 5xx with the endpoint and time.
Alert when the rate of 429s rises; it usually means a loop, a missing cache, or a polling job running too often.
