Skip to content
Project BlueDocs
Popular pages
Guides / Getting startedQuickstartGet an API key, send your first message, and confirm delivery.API reference / MessagesPOSTSend a messageSend iMessage or SMS, with media, voice memos, and message effects./send-api-messageGuides / IntegrationsWebhooksReceive message and call events at your own endpoint.Guides / Getting startedAuthenticationCreate an API key and authenticate requests with a bearer token.AI tools / AI toolsMCP server & skillConnect Claude, Codex, Cursor, and other AI tools to Project Blue.
↑ ↓ Navigate↵ Openesc Close
Dashboard
For AI agents
View as Markdown

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

Guides