# Errors

> The error body and the status codes of the PDFluent hosted API.

> Coming soon. The hosted API is not live yet, and this page describes the planned service as of 16 November 2026. [Get notified](https://pdfluent.com/contact/?topic=hosted) when it opens.

Source: https://pdfluent.com/docs/api/errors/

A failed call returns a JSON body with a stable `code` and a `message` that names the cause:

```json
{ "error": { "code": "quality_unavailable", "message": "..." } }
```

Branch on `code`, not on `message`.

## Statuses

| Status | Meaning |
|---|---|
| `400` | The request is malformed, or an option is unknown or invalid. Unknown form fields and unknown options are refused. |
| `401` | The API key is missing or not valid. |
| `404` | The job does not exist. |
| `413` | The upload is larger than the operation accepts. |
| `422` | The document cannot be processed, for example because it is not a readable PDF. |
| `500` | The service failed while processing the call. |
| `501` | The operation or quality is not available on this deployment (`quality_unavailable`). |
| `503` | The service is temporarily unavailable. Retry shortly. |
| `504` | The call took longer than the operation allows synchronously. Run it as a job. |

The gateway in front of the operations adds its own statuses: `402` when the credit balance is too low, `403` when the account is suspended or the call is outside the trial, `409` when an idempotency key was reused, `429` when a key sends too many calls, and `502` or `503` while a region recovers. They carry the same body.

## Retrying

Retry `429`, `502`, `503` and `504` with a short, growing delay. Do not retry `400`, `401`, `413` or `422` without changing the call.
