Concurrency Limits

​

Limits

• The unit is the location, not the request. A location occupies one slot while it has any request executing. Any number of concurrent requests for the same location share that slot.
• Slots free immediately. A location’s slot is released the instant its last in-flight request finishes — success or error. There are no fixed windows and no idle timers.
• The two pools are independent. Incremental polling never blocks initial syncs, and the same location may hold one slot in each pool at the same time.
• Budgets are per credential. Limits are counted per API credential across all your processes and servers combined. Other vendors’ traffic never affects yours.
• Rejected requests cost you nothing. A 429 request is not executed, occupies no slot, and is not recorded against you. Nothing was read and no partial response was produced, so retrying is always safe.
• Sequential clients are never limited. If you sync one location at a time, you cannot reach these limits.

​

Throttled Response Contract

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1
{
  "errors": "Too many locations syncing concurrently. At most 5 locations may have initial sync requests in flight at a time.",
  "sync_type": "initial",
  "max_concurrent_locations": 5,
  "active_location_ids": [101, 102, 103, 104, 105],
  "retry_after_seconds": 1
}

​

Required Client Behavior

• MUST limit concurrent locations to 5 per sync mode. Initial and incremental are counted separately, so you may run up to 5 of each.
• MUST treat HTTP 429 as a retryable condition and wait at least retry_after_seconds (or the Retry-After header) before retrying.
• MUST NOT retry in a tight loop without a delay.
• MUST cache the access token and reuse it. Tokens are valid for 6 hours; request a new one only when the current token expires.
• SHOULD detect this limit by checking the response body for max_concurrent_locations rather than assuming every 429 is a concurrency rejection.
• SHOULD read the limit from max_concurrent_locations rather than hardcoding 5, so a future change on our side requires no change on yours.
• SHOULD parallelize freely within a location. Fetching one location’s patients, appointments, and treatments simultaneously consumes a single slot and is the most efficient way to sync.
• SHOULD set items explicitly when paging. Cursor pagination defaults to 10 records per page and accepts up to 5000; leaving it at the default makes large pulls far slower than necessary.
• SHOULD add random jitter to retry delays if you run many workers, so they do not retry in lockstep.
• SHOULD use q[fetch_modified_since] for routine polling. It returns only records with updated_at >= your timestamp and routes the request to the incremental pool, so polling never competes with initial syncs.

​

Reference Implementation

import time
import requests
def vendor_get(session, url, headers, max_attempts=5):
    for attempt in range(max_attempts):
        response = session.get(url, headers=headers)
        if response.status_code != 429:
            return response
        try:
            body = response.json()
        except ValueError:
            body = {}
        if "max_concurrent_locations" in body:
            # Location concurrency limit: a slot frees as soon as any active
            # location's last in-flight request completes.
            wait = body.get("retry_after_seconds", 1)
        else:
            # Any other throttled response: honor the header.
            wait = int(response.headers.get("Retry-After", 5))
        time.sleep(wait)
    raise RuntimeError("throttled after %d attempts" % max_attempts)

​

Verifying Your Integration