Skip to main content

HTTP status code summary

A missing, unknown, revoked, or expired x-api-key returns 401 with a specific code, listed below. Older builds returned 500 for these cases, so if you still see a 500 on a request you didn’t expect, check your API key first.

Response shape

Every response — success or error — shares one envelope. On success, data holds the payload. On error, success is false and there’s no data:
200 — success
422 — error
boolean
true on every 2xx, false otherwise.
integer
Present on errors only — mirrors the real HTTP status shown in the table above.
string
A human-readable summary — safe to show a user as-is.
array
Present only on 422 — one plain-English string per invalid field.
string
An internal code, e.g. HC-1. See the note below before matching on this.
string
A machine-readable name, e.g. error_422 or a route-specific validation.xxx_not_found.
code isn’t the same for the same kind of error across every route — a “not found” alone shows up as three different code values depending on which endpoint you called. Build your error handling around http_code, not code. See Error code reference below only if you need to distinguish the exact cause.

Errors that send calls don’t return

The three send calls (template, service message, canned response) are asynchronous. They return an error only for a bad request (422), a bad key or subscription (401, 402), or an unknown channel, template or canned response (404). Everything else is checked after the 200 has been sent, so a failure there is not returned to you. The message isn’t sent, no message record is saved, and no webhook fires.
A chatbot or AI agent on the chat does not block your send. The message is queued and sent as normal, and the chatbot or AI agent keeps running: your send does not pause or end it. The customer can get your message and the automation’s reply close together. To stop the automation first, take over the chat in Chat.

Error code reference

For when you need the exact code/name a specific route returns — every row below is a real, captured response.

400 Bad Request

401 Unauthorized

402 Payment Required

404 Not Found

409 Conflict

422 Validation failed

Broadcast errors

These come from the Broadcasts routes. The status code differs by error, so each row has its own.

500 Internal server error