​
Status codes

​
Errors from API keys

Requests made with an API key can also be refused before they reach the operation: an unusable key, a missing scope, an IP allowlist, the rate limit or an Idempotency-Key problem. Those responses carry a code field, such as API_KEY_FORBIDDEN, instead of the envelope. See Errors on the API keys page for every code.

​
404 also means “not yours”

Scoping is applied inside the query, so a record that exists but belongs to another organization is indistinguishable from one that does not exist. Both return 404. That is the intended behaviour and it is the right choice for privacy, but it does mean a 404 is not proof of absence.

​
Insufficient credits

Sending with a balance below the cost of the message raises a dedicated error. The web app detects it by matching on the message text and on status 402, and replaces the send button with an “Add credits” action. If you are writing a client, treat 402 as a distinct, recoverable condition rather than a generic failure — it is the one error where the correct response is to top up and retry the identical request.

​
Some failures arrive as HTTP 200

Two cases where the status line does not tell you what happened: Webhook test. POST /api/v1/inbound/webhooks/{id}/test always returns 200 with success: true at the envelope level, regardless of whether the webhook delivered. You have to inspect data: a successful delivery has statusCode and response, a failure has error. Delivery receipts. The gateway callback endpoint always answers OK so the provider does not retry, even when processing the receipt failed.

​
Error shape

Errors from an operation return the standard envelope with success: false and a message. The data field is generally absent rather than null-filled — for example the contact statistics endpoint never sets data on its 500 path. Because message is often assembled from an exception, its text is not a stable API. Match on the status code, not on the string. One place in the frontend scrapes the message out of a raw error with a regular expression, and that will break the moment the shape changes; do not copy that pattern.