Errors & Troubleshooting
We use standard HTTP status codes to indicate the success or failure of your API requests. In general:
2xx: Success4xx: Client error (check your input, auth, or limits)5xx: Server error (our fault or upstream issue)
All error responses return a JSON object with error (code) and message (human-readable) fields.
400 Bad Request
401 Unauthorized
| Error Code |
Meaning |
missing_auth_headers |
Headers X-Token are missing. |
invalid_token |
The API Token provided is invalid. |
token_inactive |
The API Token exists but is currently disabled. |
token_expired |
The API Token has expired. |
unauthorized |
Generic authentication failure. |
missing_signature |
Signature header is missing. |
invalid_signature |
Signature is invalid. |
signature_expired |
Signature timestamp is too old. |
402 Payment Required
| Error Code |
Meaning |
insufficient_balance |
Your wallet balance is insufficient for this operation. Top up your wallet in the dashboard. |
403 Forbidden
| Error Code |
Meaning |
ip_not_allowed |
Request IP is not in your allowlist. |
token_deleted |
The API Token has been deleted. |
no_api_access |
You do not have API access. Activate a subscription or top up your wallet. |
409 Conflict
| Error Code |
Meaning |
payg_confirm_required |
This action requires explicit confirmation that it will charge your wallet (PAYG). |
422 Unprocessable Entity
Validation errors or domain-specific logic failures.
| Error Code |
Meaning |
validation_error |
One or more inputs failed validation. |
already_exists |
The resource you are trying to create already exists. |
invalid_json |
The request body or specific field contains invalid JSON. |
invalid_amount_format |
The amount format is invalid. |
invalid_otp |
The provided OTP is invalid. |
otp_expired |
The OTP has expired. |
test_message_failed |
Sending the test message failed. |
429 Too Many Requests
| Error Code |
Meaning |
rate_limit_exceeded |
You have exceeded the global rate limit. Slow down. |
plan_limit_reached |
You have reached the usage limit of your current plan. |
payg_limit_reached |
You have reached your set PAYG spending limit. |
otp_wait_required |
You must wait before requesting another OTP. |
otp_resend_limit |
You have reached the maximum OTP resend attempts. |
too_many_attempts |
Too many failed attempts. |
500 Internal Server Error
| Error Code |
Meaning |
internal_error |
An unexpected internal error occurred. Please contact support. |
502 Bad Gateway
Connectivity issues.
| Error Code |
Meaning |
send_message_failed |
Failed to send message. |
send_media_failed |
Failed to send media. |
503 Service Unavailable
| Error Code |
Meaning |
server_down |
The server is down or unreachable. |
session_not_ready |
The WhatsApp session is starting or not ready yet. |
maintenance_mode |
The application is currently in maintenance mode. |