Concurrency Limits

​

Limits

​

How slots behave

• One slot per location. Requesting a slot for a location you already hold refreshes it with a new request_key and resets its 6-hour validity (subject to the 2-minute cooldown). The previous key for that location stops working.
• The 10 newest win. Your active slots are the 10 most recently requested. When you request an 11th, the oldest key is trimmed immediately, even if a sync is still running on it, and its requests fail with 401 {"errors": "Invalid, expired or missing request key"}.
• Any number of requests per slot. There is no cap on how many requests you send against one request_key, or how fast you page through a location.
• Rejected requests cost nothing. A 429 from the slot endpoint or a 401 from a trimmed key executes nothing, so retrying is safe.

​

Throttled slot request

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{
  "errors": ["Slot for this location was requested too recently. Try again in 97s."],
  "retry_after": 97
}

​

Recommended client behavior

• SHOULD request a slot, pull all of that location’s data, then move to the next location. One slot per location per sync run is the intended pattern.
• MUST keep parallel locations at or below your quota (10 by default). An 11th slot silently kills the oldest sync.
• MUST treat 401 on a data request as “request a fresh slot”, not as an authentication failure, when the access token is still valid.
• MUST honour retry_after (or the Retry-After header) on 429 and never retry in a tight loop.
• MUST cache the access token and reuse it for its 6-hour lifetime.
• SHOULD NOT re-request a slot per data call. Keep the request_key for the whole location pull; it lives for 6 hours.
• SHOULD set items explicitly when paging. Cursor pagination defaults to 10 records per page and accepts up to 5000.
• SHOULD use q[fetch_modified_since] for routine polling so each run touches only changed records.

​

Reference implementation

import time
import requests

BASE = "https://api.teamcaredental.com/api/v2/vendors"

def request_slot(session, token, location_id):
    while True:
        r = session.post(f"{BASE}/locations/{location_id}/slots",
                         headers={"Authorization": f"Bearer {token}"})
        if r.status_code == 429:
            body = r.json() if r.content else {}
            time.sleep(body.get("retry_after") or int(r.headers.get("Retry-After", 5)))
            continue
        r.raise_for_status()
        return r.json()["data"]["attributes"]["request_key"]

def sync_location(session, token, location_id):
    key = request_slot(session, token, location_id)
    headers = {"Authorization": f"Bearer {token}", "X-Vendor-Request-Key": key}
    for resource in ("patients", "appointments", "treatments", "ledger_transactions"):
        after = None
        while True:
            params = {"items": 5000}
            if after:
                params["after"] = after
            r = session.get(f"{BASE}/{resource}", headers=headers, params=params)
            r.raise_for_status()
            page = r.json()
            # ... store page["data"] ...
            after = page.get("pagy", {}).get("next")
            if not after:
                break

# Sequential: one location at a time never exceeds the quota.
for location_id in location_ids:
    sync_location(session, token, location_id)

​

Verifying your integration