Errors

The API uses conventional HTTP status codes and a single, predictable error body. Any non-2xx response carries a machine-readable problem document.

#Error format

Errors are returned as RFC 9457 application/problem+json:

{
  "type": "https://api.smile-app.co.il/problems/forbidden",
  "title": "Missing required scope",
  "status": 403,
  "detail": "This key needs the 'patients:read' scope."
}

Field	Type	Description
`type`	string (URI)	Stable identifier for the error category.
`title`	string	Short, human-readable summary.
`status`	integer	The HTTP status code, repeated for convenience.
`detail`	string	Context specific to this occurrence (optional).

Always branch on status (or type) rather than matching on title or detail, which are meant for humans and may be reworded.

#Status codes

Status	Meaning	What to do
`400 Bad Request`	Invalid parameters (bad cursor, malformed date, unknown filter).	Fix the request; don't retry unchanged.
`401 Unauthorized`	Missing, malformed, invalid, or revoked key.	Check the `Authorization` header and the key.
`403 Forbidden`	Valid key without the required scope.	Mint a key with the needed scope.
`404 Not Found`	The resource doesn't exist for this clinic.	Verify the id; ids are clinic-scoped.
`429 Too Many Requests`	Rate limit exceeded.	Back off and retry after the `Retry-After` window.
`500 Internal Server Error`	Unexpected server error.	Retry with backoff; if it persists, contact support.
`502 / 503`	Upstream/backend temporarily unavailable.	Retry with exponential backoff.

#Handling errors

A small, robust client checks the status, parses the problem body, and only retries on transient failures.

curl -sS -w '\n%{http_code}' https://api.smile-app.co.il/v1/patients/does-not-exist \
  -H "Authorization: Bearer sk_live_..."

{
  "type": "https://api.smile-app.co.il/problems/not-found",
  "title": "Patient not found",
  "status": 404,
  "detail": "No patient with id 'does-not-exist'."
}

Retry only transient errors

Retry 429, 500, 502, and 503 with exponential backoff. Never auto-retry 400, 401, 403, or 404 - the request will keep failing until you change it.