Errors

Errors use a stable envelope:

{
  "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.

Start

Core Concepts

Codes

​Codes

Codes