API
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. |
403 | HipaaRestricted | The workspace is HIPAA-enabled; Papers is not available. | Use a non-HIPAA workspace. |
429 | RateLimited | The workspace exceeded its request limit. | Wait 60 seconds before retrying. |
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
Treat 502 as retryable after a short backoff and 429 as retryable after 60 seconds. Treat 402 as final until you top up.