Error Reference

All errors return a consistent JSON body with error and message fields.

Error response shape

Every non-2xx response from the API includes a JSON body in the following format. The request_id field uniquely identifies the failed request — include it when contacting support. 

{
  "error": "not_found",
  "message": "Briefing not found",
  "request_id": "req_01abc123"
}

HTTP status codes

Code Status Meaning
200 OK Request succeeded.
201 Created Resource was successfully created.
202 Accepted Async job has been queued. Poll or use a webhook for the result.
400 Bad Request Validation error — invalid JSON, missing required fields, or invalid field values.
401 Unauthorized Missing or invalid API key. Check your Authorization header.
403 Forbidden Valid key but insufficient scope; or the action requires an active subscription.
404 Not Found Resource doesn't exist, or doesn't belong to your account.
409 Conflict Duplicate request — e.g. a briefing is already running for this profile.
429 Too Many Requests Rate limit exceeded. Check Retry-After header and back off.
500 Internal Server Error Unexpected server-side error. Retry with exponential backoff; report if persistent.

Error codes

The error field in the JSON body contains a machine-readable slug that tells you exactly what went wrong and how to fix it:

Error code HTTP What to do
validation_error 400 Fix the request body — check required fields and data types in the error message.
unauthorized 401 Check your API key. Ensure the Authorization: Bearer lb_api_... header is present and correct.
forbidden 403 Check that your key has the required scope, or that your account has an active subscription.
not_found 404 The resource ID is wrong, was deleted, or belongs to a different account.
conflict 409 A duplicate resource or concurrent operation conflict. Wait and retry, or check your request for duplicates.
rate_limited 429 Wait for Retry-After seconds before retrying. See the Rate Limits guide.
not_ready 404 The briefing has not completed yet. Poll again later or use a webhook to be notified when it's ready.
internal_error 500 Retry with exponential backoff. If the error persists, contact api@listenbrief.com with the request_id.

Debugging tips

Every response — including error responses — includes an X-Request-Id header containing a unique identifier for that request. When submitting a bug report or support request, always include this value so the team can locate the exact request in the logs. 

# Capture the request ID from any response
curl -i https://listenbrief.com/api/v1/briefings/job_abc123 \
  -H "Authorization: Bearer lb_api_YOUR_KEY" \
  | grep -i x-request-id

# Example output:
# X-Request-Id: req_01abc123