Errors and limits

The error envelope

Every error, from every endpoint, has the same shape. There is no second format and no bare string response.

HTTP/1.1 422 Unprocessable Entity
content-type: application/json; charset=utf-8
x-request-id: req_...

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request payload failed validation.",
    "request_id": "req_...",
    "details": {
      "issues": [
        { "path": "to", "message": "must be an E.164 number, e.g. +9665XXXXXXXX" }
      ]
    }
  }
}

Validation errors

A malformed request is a 422 with a machine-readable list of what was wrong.

• Validation failures are 422, not 400. The only 400 in the whole API is a missing workspace context.
• docs.pages.errors.validation.rules.issues
• The value you sent is never echoed back, so an error is safe to log even when the request carried something sensitive.
• Most write bodies are strict: an unrecognised field is an error rather than an ignored key. A misspelled field name fails loudly.

Error codes

The complete public catalogue: 72 codes, grouped as the platform groups them. The message column is the API's own English string, reproduced exactly — it is response data rather than documentation prose, which is why it is not translated.

Codes may be added to this list. An existing code never changes meaning or disappears without an API version bump.

HTTP statuses

The status tells you the class of problem; the code tells you which one.

Pagination

List endpoints are cursor-paginated. Read page.next_cursor and pass it back as after; stop when has_more is false.

curl "https://whats.azzamkh.sa/api/v1/messages?limit=50" \
  -H "Authorization: Bearer $WA_API_KEY"

# 200 OK
# {
#   "data": [ { "id": "msg_...", ... } ],
#   "page": { "next_cursor": "bXNnXzAxSj...", "has_more": true }
# }

# Follow the cursor. Send it back verbatim; it is opaque.
curl "https://whats.azzamkh.sa/api/v1/messages?limit=50&after=bXNnXzAxSj..." \
  -H "Authorization: Bearer $WA_API_KEY"

• An out-of-range or unparseable limit is clamped, never rejected. Asking for 5000 rows returns 100.
• The cursor is opaque. Send it back verbatim and do not decode it — a malformed one is ignored and you silently get the first page again.
• Most lists are newest-first, but templates are oldest-first. Do not assume a direction; follow the cursor.
• next_cursor is null on the last page. Loop on has_more, not on an empty data array.

Rate limiting

Rate-limited routes answer 429 with the standard headers and a retry hint in the body.

HTTP/1.1 429 Too Many Requests
ratelimit-limit: 600
ratelimit-remaining: 0
ratelimit-reset: 37
retry-after: 37

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please retry later.",
    "request_id": "req_...",
    "details": { "bucket": "messages.send", "retry_after_s": 37 }
  }
}

• Every value is in seconds, not a timestamp.
• The headers are absent when rate limiting is switched off for the environment. Treat their absence as no information, not as an unlimited quota.
• The limiter fails open: if its backing store is unreachable, requests are allowed. Never rely on it as a correctness mechanism.
• PROVIDER_RATE_LIMITED is a different thing: the upstream WhatsApp provider is throttling the channel, and no header will tell you when it stops.

What to retry

Retry with exponential backoff and jitter, and always send an Idempotency-Key on a write so a retry cannot duplicate anything.