# Statuses

Every status the API returns and what to do about it.

Application errors are JSON with a `_tag` and a `message`. Request-schema validation failures return `400` and may have an empty body, so check the HTTP status before parsing JSON.

| status | `_tag`                            | meaning                                                                       | what to do                                                            |
| ------ | --------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `400`  | `InvalidRequest` or an empty body | The request is invalid.                                                       | Check required fields, types, and limits against the request schema.  |
| `401`  | `Unauthorized`                    | Key missing, unknown, or revoked.                                             | Send a live key as `Authorization: Bearer` or `X-API-Key`.            |
| `402`  | `PaymentRequired`                 | No credit left for this call. `topUpUrl` points at the console.               | Top up in the console.                                                |
| `403`  | `InsufficientScope`               | The key lacks the scope for this product.                                     | Create a key with the `papers` scope.                                 |
| `429`  | `RateLimited`                     | The workspace exceeded its request limit.                                     | Wait 60 seconds before retrying.                                      |
| `403`  | `HipaaRestricted`                 | The workspace is HIPAA-enabled; Papers is not available.                      | Use a non-HIPAA workspace.                                            |
| `502`  | `UpstreamUnavailable`             | The search index did not answer.                                              | Retry with backoff. Metered calls that fail this way are not charged. |
| `503`  | `ContentsUnavailable`             | Public contents retrieval is intentionally disabled pending licensing review. | Do not retry; no retrieval or charge occurs.                          |

## Retrying [#retrying]

Treat `502` as retryable after a short backoff and `429` as retryable after 60 seconds. Treat `402` as final until you top up.