Skip to main content

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.

Every error response from the Batch Relay API shares the same predictable JSON envelope, making it straightforward to handle failures consistently across your integration. Rather than inspecting raw HTTP status codes alone, you can branch on the machine-readable code field and present the human-readable message directly to developers or log it for debugging. The envelope also includes links that take you straight to the relevant documentation or the dashboard action needed to resolve the problem.

​
Error Envelope

All error responses return a JSON body in the following shape: 
{
  "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..."
}

​
Envelope Fields

FieldTypeDescription
error.codestringA stable, machine-readable identifier for the error type. Safe to use in conditional logic — these codes will not change.
error.messagestringA human-readable explanation of what went wrong and, where possible, what you should do next.
error.docs_urlstringA direct link to the documentation section for this specific error code so you can quickly find context and remediation steps.
error.action_urlstringA direct link to the relevant page in the Batch Relay dashboard where you can take action to resolve the error (e.g. manage API keys or billing).
request_idstringA unique identifier for the specific API request. Include this value when contacting Batch Relay support so the team can locate your request in the system.
The request_id is always present, even when error is absent on a successful response. Save it in your logs alongside every API call to simplify troubleshooting.

​
Error Codes

The table below lists every error code the API may return, the accompanying HTTP status code, and what the error means for your request.
CodeHTTP StatusMeaning
api_key_required403The request did not include a bearer API key. Add an Authorization: Bearer <key> header to every request.
api_key_invalid403The API key supplied is not recognized. Verify you are using the correct key from your developer dashboard.
api_key_revoked403The API key was explicitly revoked. Generate a new key from the developer dashboard.
api_key_expired403The API key has passed its expiry date. Rotate to a new key from the developer dashboard.
scope_required403The API key does not have the scope required to perform this action. Use a key with the appropriate permissions.
api_account_inactive403Your API account is not currently active. Contact Batch Relay support to restore access.
billing_required402Billing must be active on your account before this request can proceed. Update your billing details in the dashboard.
invalid_json400The request body could not be parsed as valid JSON. Check for syntax errors such as trailing commas or unquoted keys.
invalid_request400One or more required fields are missing or contain invalid values. Consult the message field for specifics on which fields need attention.
internal_error500Batch Relay encountered an unexpected error and could not process your request. Retry with exponential back-off and contact support if the problem persists, quoting the request_id.

​
Handling Errors in Your Integration

When you receive an error response, a reliable pattern is to:
  1. Check the HTTP status code for a broad category (4xx = client error, 5xx = server error).
  2. Read error.code to branch to the appropriate recovery logic.
  3. Log request_id alongside the full response body for every failed request.
  4. Surface error.message to developers during debugging, or use error.docs_url to navigate directly to guidance.
curl -i https://api.batchrelay.com/v1/print-orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
For internal_error (HTTP 500) responses, implement retry logic with exponential back-off and jitter. Transient server errors typically resolve within a few seconds. If retries continue to fail, open a support ticket and include the request_id from the response.