Errors
Every failure has the same shape and a code you can test for. The message is for people. The code is for your program.
The envelope
A success is { "data": ... }. A failure is an error object, with the HTTP status on the response.
{
"error": {
"message": "The 24-hour customer service window is closed. Send an approved template message to restart the conversation.",
"code": "WINDOW_CLOSED"
}
}codeis stable. Test for it.messageis plain English and can change. Show it to a person, but do not match on it.detailsis there when it helps, for exampledetails.retryableon a send, ordetails.requiredon a missing permission.
Should I try again?
429and503: yes, after theRetry-Afterseconds, or soon.- A send that says
details.retryable: true: yes, with the sameIdempotency-Key. 502 SEND_OUTCOME_UNKNOWN: no. The message may have been delivered. Look it up withGET /messages/{id}orGET /email/messages/{id}.- Other
4xx: no. Fix the request first.
Error codes
These can come from any endpoint. Each endpoint page lists the ones it adds.
- 400
BAD_REQUESTThe body isn't valid JSON.
- 400
INVALID_IDEMPOTENCY_KEYThe Idempotency-Key header is empty, longer than 255 characters or holds a line break, a tab or a non-ASCII character.
- 401
UNAUTHORIZEDMissing, malformed or revoked API key.
- 403
MISSING_SCOPEThe key lacks the permission this endpoint needs.
details.requirednames it,details.grantedlists the key's permissions. - 403
BRAND_CLOSEDThe account is closed: its keys no longer work.
- 404
NOT_FOUNDThe resource or endpoint doesn't exist in this workspace.
- 409
CONFLICTA concurrent request changed the same record. Retry.
- 409
IDEMPOTENCY_CONFLICTThis Idempotency-Key was used in the last 24 hours for a different request (another endpoint or body). Use a new key.
- 409
IDEMPOTENCY_IN_PROGRESSA request with this key is still running: send it again shortly to get its answer.
details.interruptedtrue: the first one was cut off and its outcome is unknown. - 409
OPT_OUT_ON_RECORDSubscribing somebody who opted out needs optInEvidence.
- 409
NO_MESSAGES_SELFThe person asked for no messages at all; only their own START undoes it.
- 413
PAYLOAD_TOO_LARGEThe JSON body is over 1 MB (10 MB for bulk contacts).
- 422
VALIDATION_ERRORA field is missing or invalid; message names the field.
- 429
RATE_LIMITEDToo many requests (1,200 a minute per key and 600 sends a minute per key; 3,600 and 1,800 across all the keys of your workspace). Wait for the Retry-After seconds;
details.limitsays which limit. - 500
INTERNAL_ERRORUnexpected server error. Retry later.
- 502
SEND_FAILEDWhatsApp had a temporary problem sending. Retry later.
- 502
SEND_OUTCOME_UNKNOWNWhatsApp did not answer a send, so it may have been delivered. Do not retry it. GET /messages/{id} shows what the panel recorded;
error.messagesays whether a later confirmation can be matched to it. - 503
RESTART_NEEDEDThe panel was updated while running and needs a restart before this works.

