# Errors

Extract.FAST errors are code-first. Branch on HTTP status and the stable `error` code, not English prose.

## Shape

```json
{
  "error": "request.invalid_extension",
  "detail": "Extraction does not support '.xyz'.",
  "isRetryable": false,
  "params": {
    "extension": ".xyz"
  }
}
```

## Common status codes

| Status | Meaning |
| --- | --- |
| `400` | Invalid request, options, workflow, or content type. |
| `401` | Missing or invalid API key. |
| `402` | Not enough credits or plan access. |
| `403` | Pro access required for API jobs, or forbidden resource. |
| `404` | Job or route not found. |
| `413` | File exceeds the current tier limit. |
| `415` | Unsupported extension or detected file type mismatch. |
| `422` | File could not be probed or processed safely. |
| `429` | Rate limit or queue capacity reached. |
| `503` | Temporary provider or queue unavailability. |

## Retry guidance

Retry `429` and `503` with backoff. Retry file-processing `422` only when `isRetryable` is true. Do not retry malformed options or unsupported formats without changing the request.

## Pro access required

Protected public API job routes return `403 api_key.pro_required` when the API key belongs to a Free-tier or other non-Pro account.

```json
{
  "error": "api_key.pro_required",
  "detail": "Pro access is required to use public API job endpoints."
}
```

## Billing failures

When a job fails after debit, refund handling is automatic where the billing state allows it. API clients should not submit duplicate replacement jobs until they have inspected the failed job response and current entitlements.