WhatsApp API error codes
Every error the Wapito WhatsApp API returns is one JSON envelope: { error: { code, message, details?, request_id } }. The HTTP status says how badly the call went; the snake_case code says exactly why, and is what your client branches on. The error codes below link to each one's cause, fix steps and retry advice.
4xx — the request, the credential or the channel needs a change
| Code | HTTP | Meaning | Retry |
|---|---|---|---|
| invalid_request | 400 | Request failed validation | No |
| invalid_recipient | 400 | Recipient is not valid | No |
| unauthorized | 401 | Missing or invalid token | No |
| token_revoked | 401 | Channel token was revoked | No |
| plan_required | 402 | Premium channel required | No |
| forbidden | 403 | Action not allowed | No |
| channel_locked | 403 | Channel is locked | No |
| not_found | 404 | Resource does not exist | No |
| not_on_whatsapp | 404 | Number is not on WhatsApp | No |
| message_not_found | 404 | Message does not exist | No |
| channel_not_connected | 409 | Channel not connected | Retryable |
| channel_not_in_qr_state | 409 | Not waiting for a QR | Retryable |
| business_account_required | 409 | Needs Business app | No |
| payload_too_large | 413 | Payload is too large | No |
| unsupported_media_type | 415 | Media type rejected | No |
| webhook_url_invalid | 422 | Webhook URL rejected | Retryable |
| reachout_timelocked | 423 | Reach-outs timelocked | Retryable |
| rate_limited | 429 | Too many requests | Retryable |
| quota_exceeded | 429 | Plan quota exhausted | Retryable |
| send_rate_limited | 429 | Send queue saturated | Retryable |
| cold_send_limit | 429 | Cold-send cap reached | Retryable |
| warmup_limit | 429 | Warm-up ladder cap reached | Retryable |
5xx — Wapito or the WhatsApp engine failed
| Code | HTTP | Meaning | Retry |
|---|---|---|---|
| internal_error | 500 | Unexpected Wapito failure | Retryable |
| engine_unsupported_feature | 501 | Other engine only | No |
| feature_not_available | 501 | Not available yet | No |
| engine_error | 502 | WhatsApp engine error | Retryable |
| engine_unavailable | 503 | Engine unreachable | Retryable |
| engine_timeout | 504 | Engine did not answer in time | Retryable |
Related
Reference
Try it on your own number
Create a channel, link a WhatsApp number by QR or pairing code, and call the API in a couple of minutes. The Sandbox plan is free and needs no card.