Limits & Quotas

The Nymbl Customer API enforces limits at two levels: throttling and monthly quotas applied per customer at the API Gateway, and OData query limits enforced by the application.

---

Throttle Rates

Throttle limits control how many requests your integration can make per second. Exceeding the rate limit results in a 429 Too Many Requests response.

Burst limit is the maximum number of requests that can be made in a short burst before the sustained rate limit takes effect.

Operation	Sustained Rate (req/s)	Burst
Read — GET / (all entity endpoints)	2	5
Document Download — GET /document	1	3

---

Monthly Request Quota

Monthly Request Limit	Reset Period
10,000	Calendar month

The quota counts every billable API request. Requests that are throttled (rejected with 429) do not count against the quota.

Monthly quotas reset at midnight UTC on the first day of each calendar month. There is no carry-over of unused quota from one month to the next.

Contact your Nymbl account manager to request a quota increase.

---

OData Query Limits

The following limits apply to all OData queries. They are enforced by the API and cannot be overridden.

Page Size

Limit	Value
Maximum records per page ($top)	100

If $top is omitted or set higher than 100, the API automatically caps the result to 100 records. Use $skip with repeated requests to page through larger datasets. See the Pagination Guide for examples.

Expand Depth

Limit	Value
Maximum $expand nesting depth	3 levels

Requests that exceed 3 levels of nested $expand return a 400 Bad Request with the message:

Expansion depth exceeded maximum of 3 levels

See the Expanding Relations Guide for guidance on structuring expand queries.

Filter Complexity

There is no hard limit on $filter expression complexity, but highly complex filters may time out at the database level and return a 500 error. Prefer indexed fields such as id, patient_id, appointment_date, and status in filter expressions for best performance.

---

Error Responses

HTTP Status	Meaning
429 Too Many Requests	Throttle limit exceeded — back off and retry
400 Bad Request	OData query limit violated (e.g., expand depth exceeded)

Handling 429 Responses

When you receive a 429, implement exponential backoff:

import time
import requests

def request_with_backoff(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        wait = 2 ** attempt  # 1s, 2s, 4s, 8s, 16s
        time.sleep(wait)
    raise Exception("Max retries exceeded")