SmileCloudDocs

Rate limits

To keep the API fast and fair for every clinic, requests are rate limited per API key. Well-behaved clients rarely hit the limit; when they do, the response tells them exactly how long to wait.

#How limits work

Limits are applied per key using a rolling window. When you exceed the limit, the API responds with 429 Too Many Requests and a Retry-After header indicating how many seconds to wait before retrying.

text
HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/problem+json
json
{
  "type": "https://api.smile-app.co.il/problems/rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Too many requests. Retry after 2 seconds."
}

#Staying under the limit

Page wide, not deep

Use the maximum limit=100 on list endpoints and the concise response format to fetch more per request. Cache catalog data (branches, providers, types) - it changes rarely.

  • Batch and cache. Catalog and reference data is stable; fetch it once and reuse it.
  • Avoid tight polling. Prefer webhooks over polling for changes - you'll get events pushed to you instead of hammering the API.
  • Spread bulk work. When backfilling, add a small delay between pages rather than firing requests in parallel bursts.

#Handling 429 responses

Respect Retry-After and use exponential backoff with jitter for repeated failures:

bash
attempt=0
until resp=$(curl -fsS https://api.smile-app.co.il/v1/appointments \
  -H "Authorization: Bearer sk_live_..."); do
  attempt=$((attempt + 1))
  [ "$attempt" -ge 5 ] && break
  sleep $((2 ** attempt))
done

If you consistently need higher throughput for a legitimate integration, contact SmileCloud support to discuss your use case.

PreviousErrorsNextScopes