Errors & Rate Limits
Standard HTTP status codes, error payload schemas, and rate limit policies applied by the Wahide API Gateway.
Standardized Error Responses
All non-2xx responses return a consistent JSON schema with machine-readable error codes and human-friendly troubleshooting messages.
Standard Error Schema
When an error occurs, Wahide returns a standardized response envelope:
Error Envelope
{
"success": false,
"message": "Invalid recipient phone number format",
"error": "INVALID_PHONE_NUMBER",
"additional_info": {
"field": "phone",
"received": "0812345",
"expected": "E.164 format with country code (e.g., 628123456789)"
}
}HTTP Status Code Matrix
| Status | Code | Description |
| :--- | :--- | :--- |
| `200 OK` | Success | Request succeeded. Messages queued or dispatched. |
| `201 Created` | Resource Created | Device slot, contact, or campaign successfully created. |
| `400 Bad Request` | Validation Error | Missing required fields, invalid phone number, or malformed JSON. |
| `401 Unauthorized` | Auth Error | Missing or invalid `Authorization: Bearer <key>` header. |
| `403 Forbidden` | Access Denied | Insufficient permissions or quota exhausted. |
| `404 Not Found` | Resource Missing | Device ID, contact ID, or campaign ID does not exist. |
| `429 Too Many Requests` | Rate Limit Exceeded | Request velocity exceeded the tier threshold. Backoff requested. |
| `503 Service Unavailable` | Gateway / WA Disconnected | Target WhatsApp device is offline or disconnected. |
Rate Limit Policies
Rate limits are enforced at the API gateway layer per tenant API Key to protect system stability and WhatsApp number health:
* **Free / Sandbox**: 60 requests/minute
* **Pro Tier**: 600 requests/minute
* **Enterprise Tier**: Custom dedicated throughput with Redis Stream buffer
When rate limited, the API returns HTTP `429 Too Many Requests` alongside these standard response headers:
* `X-RateLimit-Limit`: Maximum allowed requests in the window.
* `X-RateLimit-Remaining`: Remaining requests allowed in the current minute.
* `Retry-After`: Seconds to wait before attempting another request.
Best Practice: Automated Retries with Exponential Jitter
When handling `429 Too Many Requests`, inspect the `Retry-After` header and implement exponential backoff with random jitter to prevent thundering-herd issues.
On this page