Errors

Every non-2xx response uses a consistent JSON format. Classify errors by stable error.code, not the human-readable message.

Error response format

{
  "error": {
    "code": "validation_error",
    "message": "The request could not be validated.",
    "request_id": "req_demo_001",
    "details": {
      "fields": [
        { "path": "recipient.phone_number", "code": "invalid_e164" }
      ]
    }
  }
}

details is optional and machine-readable. Unknown detail fields should be ignored.

Request correlation

Every response includes an X-Request-Id header, and error bodies repeat it as error.request_id. Log that identifier with the failed operation and provide it to Brightalk support. Do not log API keys or full contact data. You may send X-Request-Id using 1–64 characters from A-Z, a-z, 0-9, ., _, :, or -. Brightalk replaces a missing or invalid value with a generated identifier.

Authentication distinctions

Condition	HTTP status and code
`Authorization` is missing or does not have exact bearer syntax	`401 authentication_required`
Bearer syntax is valid, but the key is unknown or revoked	`401 invalid_api_key`
The key is expired	`401 api_key_expired`

These responses describe credential usability without revealing resources belonging to another organization.

Status and error catalog

HTTP status	Stable error codes
`400`	`unsupported_version`, `validation_error`, `invalid_json`, `unsupported_destination`, `idempotency_key_required`
`401`	`authentication_required`, `invalid_api_key`, `api_key_expired`
`403`	`organization_not_enabled`, `insufficient_scope`, `recipient_blocked_by_policy`
`404`	`resource_not_found`
`405`	`method_not_allowed`
`409`	`resource_state_conflict`, `contact_identity_conflict`, `idempotency_conflict`, `idempotency_in_progress`, `duplicate_active_run`
`413`	`request_too_large`
`429`	`rate_limit_exceeded`
`500`	`internal_error`

A known path with an unsupported method also includes Allow. Retry-After appears where waiting before another attempt is meaningful. Error responses never expose implementation names, private payloads, query details, or stack traces.

Recording download errors use a different, simpler body

The signed URL returned as download_url is not part of the versioned JSON API above — it is served from a different host with no API key, and a failed request returns {"error": "<code>"}, a bare string code with no message, request_id, or details. Two of its codes carry a contract you must act on differently:

HTTP status	Code	Meaning	What to do
`503`	`source_access_denied`	The upstream storage refused access. This is commonly a temporary or reversible condition on our side.	Retry with backoff. Do not give up on the recording.
`410`	`media_unavailable`	The upstream storage confirmed the object no longer exists. This code is only returned on that confirmation.	Stop retrying. This is permanent.

Treat these as opposites, not degrees of the same failure: 503 means try again later, 410 means the bytes are gone for good. A sync job that collapses both into “give up” will silently abandon recordings that come back on retry. The other codes on this URL (403 invalid_link, 404 not_found, 502 upstream_unavailable, 503 server_configuration_error) do not carry this specific retry/no-retry contract, but 502 and 503 server_configuration_error are also safe to retry with backoff — both mean a problem on our side, not a permanent statement about the recording.

Get started

API fundamentals

Core concepts

Guides

Release information

API reference

Error response format

Request correlation

Authentication distinctions

Status and error catalog

Recording download errors use a different, simpler body

​Error response format

​Request correlation

​Authentication distinctions

​Status and error catalog

​Recording download errors use a different, simpler body

Error response format

Request correlation

Authentication distinctions

Status and error catalog

Recording download errors use a different, simpler body