> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Parse the consistent REST API error response format and request identifier.

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

## Error response format

```json theme={null}
{
  "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.