Errors
Use the HTTP status code to classify a failed request. JSON error responses include a human-readable message; some responses also include a stable code, required_scope, or field-specific errors. Message text may be localized and should not be used as a machine-readable error code.
HTTP status codes
| Status | Meaning | Recommended action |
|---|---|---|
200, 201, 202 | Successful read/action, resource created, or operation accepted. | For asynchronous or WhatsApp operations, follow the returned state. |
401 | Missing, invalid, expired, or revoked key. | Verify the Bearer token. |
402, 403 | Inactive subscription, inactive account, unavailable feature, or insufficient scope. | Review subscription state and permissions. |
404 | Resource not found or outside the key's data boundary. | Verify the key owner and resource ID. |
409 | Conflicting reference, incompatible state, or idempotency conflict. | Inspect the response; honor Retry-After if present. |
422 | Invalid parameters, fields, or media. | Correct the fields described in errors. |
429 | Rate limit, quota, connection allowance, or capacity reached. | Honor Retry-After if present; review plan limits. |
502, 503, 504 | Temporary gateway or service failure. | Check the operation state before retrying with the same idempotency key. |
Handling validation failures
Request JSON responses using Accept: application/json. Read individual field errors where provided, and preserve the original request context in your application without logging credentials or private message content.
Retry policy
Retry transient transport failures with bounded exponential backoff and jitter. Do not repeatedly retry authentication or validation failures. A 429 may indicate a monthly quota or a capacity limit, rather than a short-lived rate limit; retrying immediately will not resolve it.