Errors
Errors return HTTP 4xx/5xx with a consistent JSON body:
{
"success": false,
"error": {
"code": "INSTANCE_NOT_CONNECTED",
"message": "The WhatsApp instance is not connected.",
"request_id": "uuid"
}
}Common codes
| Code | HTTP | Meaning |
|---|---|---|
| UNAUTHORIZED | 401 | Missing or invalid API key |
| FORBIDDEN | 403 | Key lacks required scope |
| INSTANCE_NOT_FOUND | 404 | Unknown instance_id for your org |
| INSTANCE_NOT_CONNECTED | 400 | Live send while disconnected |
| RATE_LIMIT_EXCEEDED | 429 | Too many requests |
| INVALID_WEBHOOK_URL | 400 | Webhook URL blocked or invalid |
| EVOLUTION_ERROR | 502 | Upstream WhatsApp engine error |