# Errors

Every error has the same shape and an HTTP status that matches its `type`:

```json
{
  "error": {
    "type": "invalid_request",
    "code": "validation_failed",
    "message": "The operations.0.width field must be between 1 and 20000.",
    "param": "operations.0.width",
    "request_id": "1234"
  }
}
```

Branch on `code`; show `message` to people. A validation error also lists every field under `errors`.

| Status | Type | Codes |
| --- | --- | --- |
| 401 | `authentication` | `missing_api_key`, `invalid_api_key` |
| 402 | `payment_required` | `insufficient_credits`, `paid_account_required` |
| 403 | `permission` | `account_suspended` |
| 404 | `not_found` | `request_not_found`, `not_found` |
| 409 | `conflict` | `request_finished`, `idempotency_key_reused`, `idempotency_key_in_use` |
| 422 | `invalid_request` | `validation_failed`, `url_invalid`, `url_blocked`, `url_unresolvable` |
| 429 | `rate_limited` | `rate_limited` (wait for `Retry-After`), `concurrency_limited` (wait for one of your requests to finish), `test_mode_daily_limit` |
| 500 | `server_error` | `server_error`: retry; write to support@watermark.ws if it persists |

## A request that fails while processing

A request that was accepted but could not be processed ends with status `failed` and an `error` on the request (and its webhook), not an HTTP error:

| Code | Meaning |
| --- | --- |
| `url_blocked`, `url_invalid`, `url_unresolvable` | The source or a watermark image points somewhere the API will not fetch. |
| `source_unreachable` | The source could not be downloaded (not found, timed out, refused). |
| `source_too_large` | The source is larger than your tier allows. |
| `unsupported_media` | The file is not a format the endpoint accepts. |
| `encrypted_document` | The PDF is password-protected. |
| `processing_failed` | The file could not be processed. |

Failed requests are not charged.