Errors

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.
`preferred_provider_incomplete`	422	The selected provider cannot fulfill every line. Review `unsupported_lines`, then submit a new quote request with an explicit provider.
`split_fulfillment_unavailable`	422	Split fulfillment is not enabled. Use `studio_default` or `single_provider` for a complete single-provider order.
`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.
`provider_routing_unconfigured`	503	Provider routing is not configured on this deployment. Retry after the service is restored.
`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.
`checkout_link_forbidden`	403	Use a non-anonymous key with the matching checkout-link and print-order scopes plus an authorized studio grant.
`checkout_link_not_found`	404	Check the explicit studio ID and link ID; the link may not be visible to this credential.
`checkout_link_conflict`	409	The link is no longer revocable, cannot make that lifecycle transition, or the same idempotency key has a different request fingerprint. Do not expect a replacement token.
`invalid_checkout_link`	422	Correct the recipient context, sellable, quantity, or expiry. Price and payment fields are not accepted.
`checkout_link_unavailable`	503	Retry later with the same idempotency key for creation.
`invalid_promotion_request`	400	Correct the promotion request.
`sandbox_promotion_forbidden`	403	Use a Live key with the selected studio grant and required promotion scope.
`sandbox_promotion_not_found`	404	Check the studio and promotion IDs.
`sandbox_promotion_conflict`	409	Fetch the promotion and create a fresh plan after resolving the changed state.
`invalid_sandbox_promotion`	422	Resolve the reported block in Test Mode, then create a new plan.
`sandbox_promotion_unavailable`	503	Retry the same operation with the same idempotency key.
`sandbox_promotion_failed`	502	Preserve the request ID and inspect the safe response details.

Preferred provider cannot fulfill the order

preferred_provider_incomplete is a structured 422 response from quote creation. It is not consent to choose a different provider or to split the order:

{
  "code": "preferred_provider_incomplete",
  "selected_provider": "whcc",
  "unsupported_lines": [
    {
      "line_index": 0,
      "product_id": "print-5x7",
      "available": false,
      "reason_code": "..."
    }
  ],
  "available_single_providers": [],
  "split_fulfillment_available": false,
  "docs_url": "https://docs.batchrelay.com/errors#preferred_provider_incomplete",
  "request_id": "req..."
}

unsupported_lines identifies the original zero-based order line and a stable reason code. available_single_providers lists whole-order alternatives when available. Submit a new request using single_provider to choose one. Do not retry with best_available: split fulfillment remains unavailable and returns split_fulfillment_unavailable.

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.

Start

Core Concepts

Product reference

Common public API codes

Preferred provider cannot fulfill the order

Managed asset errors

Other route-specific codes

​Common public API codes

​Preferred provider cannot fulfill the order

​Managed asset errors

​Other route-specific codes

Common public API codes

Preferred provider cannot fulfill the order

Managed asset errors

Other route-specific codes