Browse the docs

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.

422 Unprocessable Entity
{
  "error": {
    "message": "The 24-hour customer service window is closed. Send an approved template message to restart the conversation.",
    "code": "WINDOW_CLOSED"
  }
}
  • code is stable. Test for it.
  • message is plain English and can change. Show it to a person, but do not match on it.
  • details is there when it helps, for example details.retryable on a send, or details.required on a missing permission.

Should I try again?

  • 429 and 503: yes, after the Retry-After seconds, or soon.
  • A send that says details.retryable: true: yes, with the same Idempotency-Key.
  • 502 SEND_OUTCOME_UNKNOWN: no. The message may have been delivered. Look it up with GET /messages/{id} or GET /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.

  • 400BAD_REQUEST

    The body isn't valid JSON.

  • 400INVALID_IDEMPOTENCY_KEY

    The Idempotency-Key header is empty, longer than 255 characters or holds a line break, a tab or a non-ASCII character.

  • 401UNAUTHORIZED

    Missing, malformed or revoked API key.

  • 403MISSING_SCOPE

    The key lacks the permission this endpoint needs. details.required names it, details.granted lists the key's permissions.

  • 403BRAND_CLOSED

    The account is closed: its keys no longer work.

  • 404NOT_FOUND

    The resource or endpoint doesn't exist in this workspace.

  • 409CONFLICT

    A concurrent request changed the same record. Retry.

  • 409IDEMPOTENCY_CONFLICT

    This Idempotency-Key was used in the last 24 hours for a different request (another endpoint or body). Use a new key.

  • 409IDEMPOTENCY_IN_PROGRESS

    A request with this key is still running: send it again shortly to get its answer. details.interrupted true: the first one was cut off and its outcome is unknown.

  • 409OPT_OUT_ON_RECORD

    Subscribing somebody who opted out needs optInEvidence.

  • 409NO_MESSAGES_SELF

    The person asked for no messages at all; only their own START undoes it.

  • 413PAYLOAD_TOO_LARGE

    The JSON body is over 1 MB (10 MB for bulk contacts).

  • 422VALIDATION_ERROR

    A field is missing or invalid; message names the field.

  • 429RATE_LIMITED

    Too 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.limit says which limit.

  • 500INTERNAL_ERROR

    Unexpected server error. Retry later.

  • 502SEND_FAILED

    WhatsApp had a temporary problem sending. Retry later.

  • 502SEND_OUTCOME_UNKNOWN

    WhatsApp did not answer a send, so it may have been delivered. Do not retry it. GET /messages/{id} shows what the panel recorded; error.message says whether a later confirmation can be matched to it.

  • 503RESTART_NEEDED

    The panel was updated while running and needs a restart before this works.