Skip to content
Last updated

Rate limiting

The Dentally NexGen API enforces rate limits to protect platform stability and ensure fair access for all integrations.

Understanding how limits work helps you build integrations that stay within bounds and recover gracefully when a limit is reached.

How limits are configured

Hourly quotas are set per product and per practice when your integration is onboarded. Dentally may adjust limits as your integration's needs evolve.

LimitScopeMeaning
Product quotaYour integration across all practicesMaximum API requests in a rolling one‑hour window, summed over every X-Practice-Id you call.
Subscription quotaYour integration for one practiceMaximum API requests in a rolling one‑hour window for a single X-Practice-Id.

Spike arrest

A spike arrest limits how many requests you can send in a short burst. It protects the platform and prevents your hourly quota from being consumed in a few seconds of heavy concurrency.

Rate10 requests per second
ScopePer product and practice — your credentials together with X-Practice-Id

Each practice you call has its own spike‑arrest window. Sending 10 requests per second to practice A does not affect practice B.

When spike arrest triggers, the API responds with 429 Too Many Requests. This is separate from hourly quota exhaustion; the detail field in the response body distinguishes the two cases (see When a limit is exceeded).

Hourly quotas

Up to two independent hourly quotas may apply. Both use a rolling one‑hour window: the clock does not reset on the hour; instead, each request's timestamp falls out of the window one hour after it was made.

Both quotas are evaluated on every request. Hitting either limit returns 429 Too Many Requests.

Response headers

Successful responses (2XX) and quota‑exceeded responses (429) may include rate‑limit headers so clients can throttle proactively.

Hourly quota headers

Present when the corresponding quota is configured for your product:

HeaderMeaning
RateLimit-Product-LimitMaximum requests allowed in the current product window.
RateLimit-Product-RemainingRequests remaining in the current product window.
RateLimit-Product-ResetUnix timestamp (milliseconds) when the oldest counted request falls out of the product window.
RateLimit-Subscription-LimitMaximum requests allowed in the current practice window.
RateLimit-Subscription-RemainingRequests remaining in the current practice window.
RateLimit-Subscription-ResetUnix timestamp (milliseconds) when the oldest counted request falls out of the practice window.

Monitor both product and subscription headers. An integration that spreads load across many practices can exhaust the product quota even when each individual practice still has headroom.

Spike arrest headers

When spike arrest blocks a request, the response uses a simpler header set:

HeaderValueMeaning
RateLimit-Limit10Maximum requests per second for this product and practice.
RateLimit-Remaining0No capacity left in the current one‑second window.
RateLimit-Reset1Seconds to wait before retrying.

When a limit is exceeded

All rate‑limit failures return 429 Too Many Requests with a Problem Details body:

{
  "type": "https://api.dentally.co/problems/too-many-requests",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "The request exceeded the configured rate limit."
}

When spike arrest is the cause, detail is instead:

The request exceeded the configured spike arrest limit.

Branch on status and inspect detail (or the response headers above) to decide how long to wait before retrying.

Handling guidance

  • Smooth your traffic. Spread requests over time instead of firing large parallel batches. Spike arrest is the first limit you are likely to hit if you burst too aggressively.
  • Respect response headers. Track RateLimit-*-Remaining and back off as counts approach zero.
  • Retry with backoff. On 429, wait before retrying:
    • Spike arrest: wait at least RateLimit-Reset seconds (typically 1).
    • Hourly quota: wait until the relevant RateLimit-*-Reset timestamp has passed. Add jitter so many clients do not retry in lockstep.
  • Reuse access tokens. Requesting a new token on every API call is unnecessary and may itself hit limits. See Authentication.
  • Paginate efficiently. Use the largest limit your client can process to reduce round trips. See Pagination.

Pagination

Errors