Skip to content
DutiesBook API
Open app

Error codes

Complete reference for all error codes returned by the External API.

All error responses follow this consistent structure:

4xx / 5xx
{
"success": false,
"error": {
"code": "AUTH_001",
"message": "Human-readable error description"
}
}

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)

{
"success": false,
"error": {
"code": "AUTH_001",
"message": "Missing required credentials. Please provide X-Account-Id, X-Api-Key, and X-Secret-Key headers."
}
}

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)

{
"success": false,
"error": {
"code": "VAL_001",
"message": "Invalid phone number format. Use E.164 format (e.g., +1234567890)"
}
}

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

{
"success": false,
"error": {
"code": "RES_001",
"message": "Channel not found"
}
}

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)

{
"success": false,
"error": {
"code": "BIZ_005",
"message": "Template requires 3 body variables but 2 were provided"
}
}

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

{
"success": false,
"error": {
"code": "APT_006",
"message": "This booking request was already handled"
}
}

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

{
"success": false,
"error": {
"code": "SRV_002",
"message": "Failed to send message via WhatsApp API"
}
}

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)

{
"success": false,
"error": {
"code": "RATE_001",
"message": "Rate limit exceeded. Maximum 100 requests per minute. Please try again later."
}
}
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);
}
}
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}')
Always check the error code - Use specific handling for known error codes
Retry on server errors - Use exponential backoff for transient failures
Don’t retry validation errors - Fix the request data instead
Log server errors - Include error code and message for debugging
Handle auth errors gracefully - Prompt for credential verification