Errors - Batch Relay API

Batch Relay returns a flat JSON error envelope. Read code in client code and keep request_id when contacting support.

{
  "code": "invalid_api_key",
  "message": "A valid Batch Relay API key is required.",
  "error": "A valid Batch Relay API key is required.",
  "docs_url": "https://docs.batchrelay.com/errors#invalid_api_key",
  "request_id": "req_771a19ae3f936e3f6a051e2d38f47d04"
}

The hosted API returns 401 invalid_api_key when the bearer token is missing, unknown, revoked, or belongs to another API environment. Do not parse the human message to distinguish those cases.

Common public API codes

Code	HTTP	What to do
`invalid_api_key`	401	Send a current key for the target environment.
`invalid_anonymous_session`	401	Create a new anonymous session; the current token is invalid, revoked, or expired.
`anonymous_session_rate_limited`	429	Wait for the `Retry-After` interval or use an account-owned Test API key.
`anonymous_session_unavailable`	503	Retry later or use an existing Test API key.
`anonymous_session_edge_unavailable`	503	Use `https://api.batchrelay.com`; session issuance must pass through the public gateway.
`api_key_forbidden`	403	Create a key with the route’s required scope.
`idempotency_key_required`	400	Send a non-empty `Idempotency-Key` where the route requires one.
`invalid_request_json`	400	Fix the JSON body and remove unknown fields.
`order_validation_failed`	422	Fetch the current catalog and correct the product, options, media, or address.
`invalid_provider_selection`	422	Use one supported provider ID or remove an invalid explicit choice.
`provider_product_unavailable`	422	Change the product or provider. Batch Relay does not substitute a lab.
`shipping_service_unavailable`	422	Re-quote the order or choose another currently eligible service.
`provider_shipping_quote_required`	422	Quote the complete order before attempting payment or submit.
`shipping_frozen_quote_required`	422	One-day shipping cannot be used until the provider quote can be frozen.
`quote_id_required`	400	Submit a server-created quote ID.
`quote_not_found`	404	Check that the quote belongs to the same account and environment.
`quote_expired`	409	Create a new quote.
`idempotency_conflict`	409	Use a new idempotency key for materially different input.
`payment_method_required`	402	Add an active billing method in the developer dashboard.
`fulfillment_unavailable`	503	The selected provider lane is not enabled. Do not retry by changing providers silently.
`live_mode_billing_unavailable`	503	Live Mode billing is not configured on this deployment.
`endpoint_not_found`	404	Check the OpenAPI document for the exact path and method.

Managed asset errors

Code	HTTP	What to do
`invalid_asset_source`	422	Supply exactly one of `url` or `asset_id`.
`unsafe_asset_url`	422	Use a publicly routable HTTPS URL without credentials or private-network resolution.
`invalid_asset_media`	422	Upload JPEG, PNG, or TIFF bytes with safe dimensions and a matching `Content-Type`.
`asset_too_large`	413	Reduce the source image below the 16 MiB ingestion limit.
`managed_asset_resolution_unavailable`	503	The deployment cannot resolve managed assets. Retry only after the service is restored.
`asset_ingestion_failed`	502	The deployment could not ingest the source image. Confirm that the source is reachable over HTTPS.

The pending managed-assets diagnostic rollout replaces generic source-fetch failures with source_fetch_failed (502). It distinguishes a non-2xx source response, timeout, unreachable host, and invalid media without exposing the upstream response body.

Other route-specific codes

Some dashboard, internal, Stripe-webhook, settlement, and template-render routes return more specific codes. The live OpenAPI document is the route-level contract. For an unexpected code, preserve the request_id and inspect the route’s documented response before retrying.