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.
production_not_supported	400	Production print orders are not enabled yet.
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.