Skip to main content

Rate Limits and Retries

How to handle 429 Too Many Requests and build an integration that stays reliable under load.

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: POST /v1/insurance/eligibility and POST /v1/patients/{patientId}/insurances/{insuranceId}/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:

  1. Stop sending requests to that endpoint briefly.

  2. Retry the same request after a delay.

  3. 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.

  4. 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, and POST /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.

Did this answer your question?