Errors

Errors use HTTP status codes and a body in the format of RFC 9457, Content-Type: application/problem+json:

{
  "type": "about:blank",
  "status": 422,
  "code": "validation_failed",
  "title": "Check the form fields",
  "errors": [
    { "field": "variables.promo_code", "code": "required", "message": "Fill in this field" }
  ]
}

Field
status	The HTTP status.
code	What went wrong, machine-readable and stable. Build your logic on it.
title	A short text for people, in the language of Accept-Language. It may change.
errors	For validation_failed and some others: each wrong field with its own code and message.

Some codes carry more members: shortage (insufficient_funds), retry_after (daily_limit_reached), segments and max_segments (message_too_long).

Field errors

errors[].field is the path of the field in the body (to, variables.promo_code, fields.amount). errors[].code is the failed rule, for example required, max, in (not an allowed value), prohibited (not allowed together with another field), string, field_value (a contact field value of the wrong type).

Codes

Status	Code	Meaning
400	bad_request	The request cannot be read, for example the body is not valid JSON.
401	api_key_invalid	No Authorization: Bearer header, or the key is unknown or revoked. After 20 failed key checks in a minute the address gets too_many_requests for the rest of the minute.
403	api_key_ip_denied	The key has an IP allowlist and the request came from another address.
403	account_suspended	The account is suspended. Contact support.
403	api_key_scope	The key lacks the permission of the endpoint (send, status or contacts).
403	free_text_not_allowed	An SMS with an own text, but the account may only send templates. Ask your manager to enable it.
404	not_found	No such path, or no such object in the account (a message of another account or of the other key mode).
404	template_not_found	The account has no approved template with this name in the channel.
405	method_not_allowed	The path exists but not with this HTTP method; the Allow header lists the methods.
413	payload_too_large	The body is over 64 KiB.
422	validation_failed	Some fields are wrong: errors lists each field with its code and a message.
422	invalid_number	The number is not a valid phone number. Send it in E.164: +, the country code and the number, without spaces or dashes.
422	recipient_stopped	The number is on one of the stop lists of the account (opted out or added by your team).
422	destination_unavailable	The channel does not deliver to this country for the account: no route, no price, or (SMS) no sender name for the country. Ask your manager.
422	message_too_long	The SMS needs more segments than allowed; segments and max_segments say by how much.
409	template_unavailable	WhatsApp only: the template version is approved in ACE SEND but not (or no longer) approved by WhatsApp for sending, for example paused or disabled. Check the template in the console.
409	insufficient_funds	The available balance does not cover the price; shortage is the missing amount. Top up and retry.
409	idempotency_conflict	The Idempotency-Key was used within 24 hours for another body, or by a key of the other mode (test or live).
409	idempotency_in_progress	The first request with this Idempotency-Key is still running. Retry in a moment.
429	too_many_requests	Over the rate limit. Wait for the seconds of the Retry-After header.
429	daily_limit_reached	The daily message limit of the account (or of test keys: 1000 a day) is reached. It resets at midnight in the time zone of the account; retry_after and the Retry-After header say when. Ask your manager to raise the limit.
500	server_error	Something failed on our side. Retry with the same Idempotency-Key.
503	service_unavailable	Maintenance or overload. Retry later with the same Idempotency-Key.

New codes may be added. Handle an unknown code by its HTTP status: 4xx — the request needs a change, 5xx — retry later.