Error codes
Complete reference for all error codes returned by the External API.
Error response format
Section titled “Error response format”All error responses follow this consistent structure:
{ "success": false, "error": { "code": "AUTH_001", "message": "Human-readable error description" }}Authentication errors (AUTH)
Section titled “Authentication errors (AUTH)”401 / 403 Status codes
These errors indicate authentication or authorization problems with your API credentials.
AUTH_001 401 Missing credentials (one or more headers missing)
AUTH_002 401 Invalid Account ID format
AUTH_003 401 Invalid API Key format
AUTH_004 401 Invalid Secret Key format
AUTH_005 401 Credentials mismatch (no matching API key found)
AUTH_006 403 IP not allowed (IP not in whitelist)
AUTH_007 403 Permission denied (API key lacks required permission)
AUTH_008 403 Channel access denied (API key cannot access this channel)
Example response
Section titled “Example response”{ "success": false, "error": { "code": "AUTH_001", "message": "Missing required credentials. Please provide X-Account-Id, X-Api-Key, and X-Secret-Key headers." }}Validation errors (VAL)
Section titled “Validation errors (VAL)”400 Bad Request
These errors occur when request data is invalid or malformed.
VAL_001 400 Invalid phone number format
VAL_002 400 Invalid template ID
VAL_003 400 Invalid channel ID
VAL_004 400 Missing required field
VAL_005 400 Invalid variables format
VAL_006 400 Too many recipients (max 10,000)
VAL_007 400 Invalid JSON in request body
VAL_008 400 Duplicate keys in JSON request body
VAL_009 400 Missing fallback variables for per-recipient overrides
VAL_010 400 Media required (template has IMAGE/VIDEO/DOCUMENT header)
VAL_011 400 Media not supported (template has no media header)
VAL_012 400 Flow not supported (template has no WhatsApp Flow button)
VAL_013 400 Meta rejected the message as not matching the template (parameter error)
Example response
Section titled “Example response”{ "success": false, "error": { "code": "VAL_001", "message": "Invalid phone number format. Use E.164 format (e.g., +1234567890)" }}Resource errors (RES)
Section titled “Resource errors (RES)”404 Not Found
These errors occur when a requested resource does not exist.
RES_001 404 Channel not found
RES_002 404 Template not found
RES_003 404 Bulk send not found
RES_004 404 Flow event not found (or past its 30-day retention window)
RES_005 404 Flow send not found (or past its 30-day retention window)
RES_006 404 Contact not found
RES_007 404 Conversation not found
RES_008 404 Webhook delivery not found
Example response
Section titled “Example response”{ "success": false, "error": { "code": "RES_001", "message": "Channel not found" }}Business logic errors (BIZ)
Section titled “Business logic errors (BIZ)”422 / 409
These errors occur when a request is valid but cannot be processed due to business rules. Most are 422 Unprocessable Entity; BIZ_006 and BIZ_007 (webhook redelivery conflicts) are 409 Conflict.
BIZ_001 422 Channel not connected
BIZ_002 422 Template not approved
BIZ_003 422 Template disabled locally
BIZ_004 422 Payment method required
BIZ_005 422 Template variable count mismatch
BIZ_006 409 Delivery already pending (webhook redelivery already queued)
BIZ_007 409 Webhook disabled (re-enable before redelivering)
Example response
Section titled “Example response”{ "success": false, "error": { "code": "BIZ_005", "message": "Template requires 3 body variables but 2 were provided" }}Appointment errors (APT)
Section titled “Appointment errors (APT)”Appointments API
Returned by the Appointments endpoints. A key limited to specific channels without the appointments WhatsApp number gets AUTH_008 on all of them.
APT_001 403 Appointments is not turned on for this organization. It is available on Enterprise plans only, added on request.
APT_002 409 No booking system is connected
APT_003 422 Your GET {baseUrl}/auth/verify did not answer 2xx with the token given
APT_004 400 The request is not valid (a missing or malformed field)
APT_005 404 Appointment not found
APT_006 409 Not pending: already accepted or rejected, or its time has passed
APT_007 409 Not active: cancelled, rejected, or in the past
APT_008 409 The WhatsApp booking form is not ready: finish the WhatsApp setup in Settings › Booking
APT_009 422 WhatsApp did not accept the booking form
APT_010 409 The organization takes bookings in DutiesBook: an admin chooses 'In your own booking system' in Settings › Booking
APT_011 409 No webhook URL is set, so no booking can be sent to you: an admin sets it in Settings › Booking
Example response
Section titled “Example response”{ "success": false, "error": { "code": "APT_006", "message": "This booking request was already handled" }}Server errors (SRV)
Section titled “Server errors (SRV)”500 Internal Server Error
These errors indicate server-side problems. Retry with exponential backoff.
SRV_001 500 Internal server error
SRV_002 500 Meta API error
Example response
Section titled “Example response”{ "success": false, "error": { "code": "SRV_002", "message": "Failed to send message via WhatsApp API" }}Rate limit errors (RATE)
Section titled “Rate limit errors (RATE)”429 Too Many Requests
These errors occur when you exceed the allowed request rate. Retry with exponential backoff.
RATE_001 429 Rate limit exceeded (max 100 requests per minute)
Example response
Section titled “Example response”{ "success": false, "error": { "code": "RATE_001", "message": "Rate limit exceeded. Maximum 100 requests per minute. Please try again later." }}Handling errors
Section titled “Handling errors”JavaScript
Section titled “JavaScript”try { const result = await client.sendMessage(options);} catch (error) { switch (error.code) { case 'AUTH_001': case 'AUTH_005': console.error('Check your API credentials'); break;
case 'AUTH_006': console.error('Your IP is not whitelisted'); break;
case 'VAL_001': console.error('Invalid phone number format'); break;
case 'BIZ_002': console.error('Template not approved - use an approved template'); break;
case 'BIZ_005': console.error('Check template variable count'); break;
default: console.error('Error:', error.message); }}Python
Section titled “Python”try: result = client.send_message(options)except APIError as e: if e.code in ('AUTH_001', 'AUTH_005'): print('Check your API credentials')
elif e.code == 'AUTH_006': print('Your IP is not whitelisted')
elif e.code == 'VAL_001': print('Invalid phone number format')
elif e.code == 'BIZ_002': print('Template not approved - use an approved template')
elif e.code == 'BIZ_005': print('Check template variable count')
else: print(f'Error: {e}')