# Errors

> The error catalogue: HTTP status, OperationOutcome issue codes and what to do for each.

Source: https://developers.anpheros.com/guides/errors

Under `/fhir/R4` errors are `OperationOutcome`; elsewhere `{"error": {"type", "message", "field"?}}`. Every response carries `Anpheros-Request-Id`; quote it when you write to support.

| HTTP | `issue.code` / `type` | Meaning | What to do |
|---|---|---|---|
| 400 | `invalid`, `structure`, `value` | malformed JSON, invalid FHIR, value not in a required value set, unsupported search parameter, unsupported scope filter | fix the request; the message names the field |
| 400 | `too-costly` | resource nesting > 64 levels, text > 10 000 chars | simplify the resource |
| 401 | `login` | missing, unknown, expired or revoked credential; consent no longer active | re-authenticate; for OAuth, refresh or re-consent |
| 403 | `forbidden` | scope, ownership (written by another organisation), read-only grant, admin only | request the right scope; write your own resource |
| 404 | `not-found` | does not exist for this caller | never assume existence from a 404 |
| 409 | `conflict` | idempotency key in progress; document already final; endpoint limit | retry shortly / use a new key |
| 410 | `deleted` | resource or file deleted | — |
| 412 | `conflict` | `If-Match` version mismatch | re-read, then update |
| 413 | `too-costly` | body or document over the limit | split or compress |
| 422 | `not-found` / `invalid` | referenced patient does not exist for you; resource moved between patients; idempotency key reused with another body | fix the reference |
| 429 | `throttled` | per-credential or per-IP rate limit | wait `Retry-After` seconds; the SDKs do this |
| 503 | `transient` | document storage unavailable | retry with backoff |
| 500 | `exception` | unexpected error, logged and audited with the request id | report the request id |