# Errors

URL: https://docs.healthcare.dev/errors

Errors are `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)):

```json
{
  "type": "https://healthcare.dev/problems/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "limit must be at most 100",
  "errors": [{ "path": "limit", "message": "Too big: expected number to be <=100" }]
}
```

Branch on `type`. Codes are stable and only ever added, never renamed.

| `type` (under `https://healthcare.dev/problems/`) | Status | What to do                                                |
| ------------------------------------------------- | ------ | --------------------------------------------------------- |
| `invalid-request`                                 | 400    | Fix the parameter named in `errors[].path`                |
| `unauthorized`                                    | 401    | Send a valid key: `Authorization: Bearer hdev_live_...`   |
| `forbidden`                                       | 403    | Your plan or key can't use this dataset                   |
| `not-found`                                       | 404    | The id doesn't exist in any release (retired ones do)     |
| `rate-limited`                                    | 429    | Wait `Retry-After` seconds, then retry                    |
| `quota-exceeded`                                  | 429    | Monthly calls used up; upgrade or wait for the next month |
| `internal`                                        | 500    | Retry with backoff; tell us if it persists                |
| `unavailable`                                     | 503    | Service degraded; retry with backoff                      |
| `dataset-unavailable`                             | 503    | The dataset has no published version yet                  |

The SDK maps these to typed errors (`NotFoundError`, `RateLimitError`, `QuotaExceededError`, ...)
and retries `rate-limited`, 5xx and network errors for you.