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`
`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.

Get started

API fundamentals

Core concepts

Guides

Release information

API reference

Error response format

Request correlation

Authentication distinctions

Status and error catalog

​Error response format

​Request correlation

​Authentication distinctions

​Status and error catalog

Error response format

Request correlation

Authentication distinctions

Status and error catalog