## Error handling

The API uses standard HTTP status codes. All error responses include a JSON body with an `error` field describing what went wrong.

### Status codes

- **200** — Message sent successfully
- **400** — Invalid request body or missing required fields
- **401** — Missing or invalid API key
- **403** — Forbidden — e.g. endpoint unavailable on trial accounts (see Trial accounts), unverified trial destination, or opted-out contact
- **409** — Conflict — a group already exists on another line, a Workflow run is already active for this contact, or a trial account has no shared line provisioned
- **429** — Rate limit exceeded (60 requests/minute per key), or the FaceTime daily dial cap
- **500** — Internal server error

Two error bodies are worth special-casing. `Pagination depth too deep` means `offset + limit` exceeded 2000 on [list messages](https://api.tryprojectblue.com/#list-messages) or [call logs](https://api.tryprojectblue.com/#call-logs) — narrow the query by date or line rather than paging deeper. `This trial account is not provisioned on a shared line` is a 409 that only trial accounts see; it means the destination is verified but the account has no shared line yet.

**Response — 401 Unauthorized**

```json
{
  "error": "Missing or invalid Authorization header"
}
```