Common errors, their causes, and how to resolve them.
A 401 is authentication: the key or token is missing, malformed, or expired. A 403 is authorization: the credential is valid but the request is out of scope — either the SMART scopes do not cover that resource type, or the resource belongs to a dataset the account cannot read. A 429 is neither; it means the account passed a daily request ceiling, and the response carries headers showing used against limit. A 429 is the one denial that is not about this request: the same URL worked earlier the same day.
The most common cause is requesting a v1 scope form against a deployment expecting v2 granular syntax, or omitting launch/patient and then reading patient-context resources. Compare the scopes you requested against the scopes the token was actually granted — they are not always the same, and at least one real vendor drops write scopes silently. See the SMART on FHIR guide.
A rejected search usually means the parameter is not declared on that deployment's CapabilityStatement, or a reference parameter was sent in a form the server will not infer a type for. Fetch metadata for the route you are calling before assuming the parameter exists — vendor routes deliberately advertise narrower parameter sets than the canonical endpoint.
Check whether you are on the Free tier, which is scoped to the sample dataset, and whether a _since or _lastUpdated filter is excluding everything. When polling for deltas, always reuse the cursor the previous Bundle returned rather than computing your own timestamp — see living data. Still stuck? Start from the quickstart or the API reference.