> ## Documentation Index
> Fetch the complete documentation index at: https://docs.batchrelay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error codes returned by the Batch Relay API.

Errors use a stable envelope:

```json theme={null}
{
  "error": {
    "code": "api_key_required",
    "message": "Supply a Batch Relay API key using Authorization: Bearer <key>.",
    "docs_url": "https://docs.batchrelay.com/errors#api_key_required",
    "action_url": "https://app.batchrelay.com/developers"
  },
  "request_id": "req..."
}
```

## Codes

| Code                           | HTTP | Meaning                                                                                              |
| ------------------------------ | ---: | ---------------------------------------------------------------------------------------------------- |
| `api_key_required`             |  403 | The request did not include a bearer API key.                                                        |
| `api_key_invalid`              |  403 | The API key is unknown.                                                                              |
| `api_key_revoked`              |  403 | The API key was revoked.                                                                             |
| `api_key_expired`              |  403 | The API key is expired.                                                                              |
| `scope_required`               |  403 | The key lacks the required scope.                                                                    |
| `api_account_inactive`         |  403 | The API account is not active.                                                                       |
| `billing_required`             |  402 | Billing must be active before this request can continue.                                             |
| `invalid_json`                 |  400 | The request body is not valid JSON.                                                                  |
| `invalid_request`              |  400 | Required request fields are missing or invalid.                                                      |
| `image_invalid`                |  422 | The image URL could not be read as a supported JPEG, PNG, or WebP image.                             |
| `image_aspect_ratio_mismatch`  |  422 | The image dimensions do not match the product's required aspect ratio.                               |
| `provider_product_unavailable` |  422 | The selected provider cannot fulfill every line. No payment was attempted.                           |
| `provider_preview`             |  422 | The provider is visible for planning but cannot receive hosted orders.                               |
| `fulfillment_unavailable`      |  503 | A provider executor or required lane-specific credentials are not enabled; no payment was attempted. |
| `invalid_api_key`              |  401 | The key is unknown, revoked, or belongs to a different API environment.                              |
| `internal_error`               |  500 | Batch Relay could not process the request.                                                           |

Image errors include a `details` object with the item index, product, actual dimensions when available, allowed ratios, and validation tolerance.