Errors | Hams AI Docs

Most error responses from the send endpoint share one body. Authentication and rate-limit failures are the exceptions, and this page describes them at the end.

The shared shape:

1 {
2   "error": "outside_messaging_window",
3   "message": "The customer service window is closed for this conversation. Send a template message instead."
4 }

error is a stable machine-readable code, so branch on it. message is written for a human reading your logs and can change at any time.

422 Unprocessable Entity

The API understood the request but cannot carry it out.

Code	What happened	What to do
`identifier_required`	The request had none of `conversation_id`, `contact_id`, or `phone_number`.	Send exactly one.
`inbox_id_required`	The request had no `conversation_id`, and no `inbox_id` to fall back on.	Add `inbox_id`.
`content_required`	`content` was missing or empty.	Send `content`. It is required even for a template send.
`invalid_phone_number`	The number is not E.164.	Use a leading `+`, then the country code, then digits only.
`unsupported_channel`	The request used `phone_number` against an inbox that cannot be addressed by number.	Only WhatsApp, Twilio, and SMS inboxes accept a phone number. Use `contact_id` elsewhere.
`contact_not_messageable`	The contact has no address this channel can reach.	Add a phone number to the contact first, or an email address for an email inbox.
`outside_messaging_window`	The request carried plain `content` outside the 24 hour window, or targeted a contact who has never written in.	Send a template instead. See Sending templates.
`contact_conflict`	The API could not save the `contact` attributes. Most often the email address already belongs to a different contact, though a malformed email lands here too.	Send the request without `contact.email`, or correct the address. The `message` field names the failing attribute.

contact_conflict is deliberately strict. Reusing the contact that owns that email address would deliver your message to that contact’s phone number, so the API refuses the request instead.

404 Not Found

1 { "error": "not_found", "message": "Couldn't find Conversation" }

The conversation_id, contact_id, or inbox_id does not exist in this account. Ids from another account read as missing, never as forbidden.

401 Unauthorized

The token is missing, invalid, or valid but issued for a different account. There is no separate forbidden response, and both cases return 401.

This response carries only the error field:

1 { "error": "You are not authorized to access this account" }

Authorization is account-level. An API key reaches every inbox, conversation and contact in the account that issued it, and a user’s token is not narrowed to the inboxes that user is assigned in the dashboard. Treat both as account-wide credentials and store them accordingly. Issue one key per integration so you can revoke it on its own.

429 Too Many Requests

The key went over 600 requests per minute. Back off and retry.

The rate limiter returns this response before the application sees the request, so the body is plain text rather than JSON:

Retry later

Partial effects

The API resolves the target before it checks the messaging window. A rejection with outside_messaging_window can therefore leave a newly created contact and conversation behind. This is intentional and safe to retry: the follow-up template send reuses them rather than creating duplicates.