Errors and status codes

The error envelope#

{"error": {"code": "outside_service_window", "message": "The customer has not messaged in the last 24 hours. Send an approved template instead."}}

Validation errors add the failing fields, keyed in dot notation:

{
  "error": {"code": "validation_failed", "message": "The to field must be an international phone number (digits, optional leading +). (and 2 more errors)"},
  "errors": {
    "to": ["The to field must be an international phone number (digits, optional leading +)."],
    "text": ["The text field is required when type is text."],
    "text.body": ["The text.body field is required when type is text."]
  }
}

Request IDs#

Every response has an X-Request-ID header, and error bodies repeat it as error.request_id. Send your own X-Request-ID (8-128 characters: letters, digits, . _ : -) to tie PaalChat's logs to yours; otherwise PaalChat makes one. Log it with failed calls and quote it when you contact PaalTech support - it identifies the request, and the send it queued, in PaalChat's logs.

Codes#

Delivery failures#

A message accepted with 202 can still fail at Meta. That is not an HTTP error: it arrives as a message.status callback with status: failed and error: {code, message}. Common codes:

Other numeric codes are Meta's error codes.

Handling strategy#

• 4xx except 429: do not retry; fix the cause or show the message.
• 429 and 5xx: retry with backoff - see Safe retries.
• Network errors on a send: retry with the same reference.