Error catalog
All errors use one format. This page lists every code. The anchor of each code is the code itself, for example #insufficient_scope.
#Sign-in and permissions (401, 403)
#authentication_required
| Status | 401 |
Class (error_type) | authentication |
| Title | Authentication required |
| Cause | No API key was sent. Send 'Authorization: Bearer <key>'. |
| Fix | Send the header 'Authorization: Bearer <key>'. |
| Safe to retry | no, change the request first |
| Returned by | 82 operations |
#api_key_invalid
| Status | 401 |
Class (error_type) | authentication |
| Title | Invalid API key |
| Cause | This API key is not valid. |
| Fix | Check the key. |
| Safe to retry | no, change the request first |
| Returned by | 82 operations |
#api_key_revoked
| Status | 401 |
Class (error_type) | authentication |
| Title | API key revoked |
| Cause | This API key was revoked. |
| Fix | Create a new key in the app. |
| Safe to retry | no, change the request first |
| Returned by | 82 operations |
#api_key_expired
| Status | 401 |
Class (error_type) | authentication |
| Title | API key expired |
| Cause | This API key has expired. |
| Fix | Create a new key in the app. |
| Safe to retry | no, change the request first |
| Returned by | 82 operations |
#insufficient_scope
| Status | 403 |
Class (error_type) | permission |
| Title | Missing permission |
| Cause | This key lacks a required permission. |
| Fix | Add the permission to the key (create a new key). |
| Safe to retry | no, change the request first |
| Returned by | 81 operations |
#ip_not_allowed
| Status | 403 |
Class (error_type) | permission |
| Title | IP address not allowed |
| Cause | This IP address is not allowed for this key. |
| Fix | Change the IP list of the key. |
| Safe to retry | no, change the request first |
| Returned by | 82 operations |
#action_not_allowed
| Status | 403 |
Class (error_type) | permission |
| Title | Action not allowed with API keys |
| Cause | This action is not available with API keys or connected assistants. Deleting data, managing the account and changing the plan are only possible in the app. |
| Fix | Do this in the app. |
| Safe to retry | no, change the request first |
#account_blocked
| Status | 403 |
Class (error_type) | permission |
| Title | Account blocked |
| Cause | This account is blocked. |
| Fix | Contact support. |
| Safe to retry | no, change the request first |
| Returned by | 41 operations |
#subscription_locked
| Status | 403 |
Class (error_type) | permission |
| Title | Subscription locked |
| Cause | The subscription or payment state blocks this function. |
| Fix | Check the subscription in the app. |
| Safe to retry | no, change the request first |
| Returned by | create_optin_confirmations, send_newsletter, control_newsletter, send_test_newsletter, send_text_message, send_template_message |
#feature_unavailable
| Status | 403 |
Class (error_type) | permission |
| Title | Function not in plan |
| Cause | This function is not included in the current plan. |
| Fix | Check the plan in the app. |
| Safe to retry | no, change the request first |
| Returned by | update_ai_reply_settings, create_automation, set_automation_status, create_media |
#bad_request
| Status | 400 |
Class (error_type) | invalid_request |
| Title | Bad request |
| Cause | The request could not be read. |
| Fix | Check the request body (valid JSON). |
| Safe to retry | no, change the request first |
| Returned by | 20 operations |
#validation_failed
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Validation failed |
| Cause | A field is not valid. |
| Fix | Correct the input. |
| Safe to retry | no, change the request first |
| Returned by | 74 operations |
#missing_parameter
| Status | 400 |
Class (error_type) | invalid_request |
| Title | Missing parameter |
| Cause | A required field is missing. |
| Fix | Add the field. |
| Safe to retry | no, change the request first |
| Returned by | 27 operations |
#unknown_parameter
| Status | 400 |
Class (error_type) | invalid_request |
| Title | Unknown parameter |
| Cause | A field is not known. |
| Fix | Remove the field. |
| Safe to retry | no, change the request first |
| Returned by | 34 operations |
#invalid_cursor
| Status | 400 |
Class (error_type) | invalid_request |
| Title | Invalid cursor |
| Cause | The cursor is expired, forged or belongs to other filters. |
| Fix | Start again without a cursor. |
| Safe to retry | no, change the request first |
| Returned by | 19 operations |
#invalid_phone_number
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Invalid phone number |
| Cause | The phone number is not valid E.164. |
| Fix | Send the number with country code, for example +4915112345678. |
| Safe to retry | no, change the request first |
| Returned by | update_business_profile, create_contact, update_contact, send_test_newsletter |
#invalid_email
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Invalid email address |
| Cause | The email address is not valid. |
| Fix | Correct the address. |
| Safe to retry | no, change the request first |
| Returned by | create_contact, update_contact |
#payload_too_large
| Status | 413 |
Class (error_type) | invalid_request |
| Title | Payload too large |
| Cause | The request body or file is too large. |
| Fix | Send less data (limits are listed per route in the docs). |
| Safe to retry | no, change the request first |
| Returned by | create_media |
| Status | 415 |
Class (error_type) | invalid_request |
| Title | Unsupported media type |
| Cause | This content type or file type is not allowed. |
| Fix | Use an allowed type. |
| Safe to retry | no, change the request first |
| Returned by | create_media |
#idempotency_key_required
| Status | 400 |
Class (error_type) | invalid_request |
| Title | Idempotency key required |
| Cause | This call needs an 'Idempotency-Key' header. |
| Fix | Send the 'Idempotency-Key' header. |
| Safe to retry | no, change the request first |
| Returned by | 23 operations |
#idempotency_key_invalid
| Status | 400 |
Class (error_type) | invalid_request |
| Title | Invalid idempotency key |
| Cause | The 'Idempotency-Key' header must be 1 to 255 visible ASCII characters. |
| Fix | Use 1 to 255 visible ASCII characters, for example a UUID. |
| Safe to retry | no, change the request first |
| Returned by | 32 operations |
#idempotency_key_reused
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Idempotency key reused |
| Cause | This idempotency key was already used with a different request. |
| Fix | Use a new key. |
| Safe to retry | no, change the request first |
| Returned by | 32 operations |
#plan_required
| Status | 400 |
Class (error_type) | invalid_request |
| Title | Plan required |
| Cause | This action needs a plan_id from a preview. |
| Fix | Request the preview first. |
| Safe to retry | no, change the request first |
| Returned by | create_automation_run, publish_landing_page, create_template_submissions |
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Contact not confirmed |
| Cause | The contact has no confirmed opt-in. |
| Fix | Get the confirmation first. |
| Safe to retry | no, change the request first |
| Returned by | unsubscribe_contact, send_text_message, send_template_message |
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Contact opted out |
| Cause | The contact has unsubscribed. |
| Fix | Never send to this contact. |
| Safe to retry | no, change the request first |
| Returned by | send_test_newsletter, send_text_message, send_template_message |
#number_suppressed
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Number suppressed |
| Cause | The number is on the suppression list. |
| Fix | Never send to this number. |
| Safe to retry | no, change the request first |
| Returned by | send_test_newsletter, send_text_message, send_template_message |
#window_closed
| Status | 422 |
Class (error_type) | invalid_request |
| Title | 24-hour window closed |
| Cause | The 24-hour window is closed. Free text is not possible. |
| Fix | Send an approved template instead. |
| Safe to retry | no, change the request first |
| Returned by | send_text_message |
#template_not_approved
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Template not approved |
| Cause | The template is not approved. |
| Fix | Check the template status. |
| Safe to retry | no, change the request first |
| Returned by | create_optin_confirmations, send_newsletter, control_newsletter, send_test_newsletter, send_template_message |
#template_variables_missing
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Template variables missing |
| Cause | Values for some template variables are missing. |
| Fix | Add the missing values. |
| Safe to retry | no, change the request first |
| Returned by | send_template_message |
#template_rejected
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Template rejected |
| Cause | WhatsApp rejected the template. |
| Fix | Change the text and submit again. |
| Safe to retry | no, change the request first |
| Returned by | send_newsletter, control_newsletter, create_template, update_template |
#whatsapp_not_connected
| Status | 422 |
Class (error_type) | invalid_request |
| Title | WhatsApp not connected |
| Cause | No WhatsApp number is connected. |
| Fix | Connect a number in the app. |
| Safe to retry | no, change the request first |
| Returned by | send_newsletter, control_newsletter, send_test_newsletter, send_text_message, send_template_message, create_template_submissions |
#test_phone_not_set
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Test number not set |
| Cause | The account has no test number. |
| Fix | Set the test number in the profile. |
| Safe to retry | no, change the request first |
| Returned by | send_test_newsletter |
#test_phone_unverified
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Test number not verified |
| Cause | The test number is not verified. |
| Fix | Verify the test number in the app. |
| Safe to retry | no, change the request first |
#recipient_limit_exceeded
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Too many recipients |
| Cause | The call has more recipients than allowed. |
| Fix | Make the audience smaller. |
| Safe to retry | no, change the request first |
#audience_empty
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Audience empty |
| Cause | The audience has no reachable contacts. |
| Fix | Check the audience. |
| Safe to retry | no, change the request first |
| Returned by | create_optin_confirmations, send_newsletter, control_newsletter |
#automation_invalid
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Automation invalid |
| Cause | The automation spec breaks a catalog rule. |
| Fix | Correct the spec (see errors). |
| Safe to retry | no, change the request first |
| Returned by | create_automation, update_automation, set_automation_status |
#landing_ops_rejected
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Operations rejected |
| Cause | Some operations were rejected. Nothing was changed. |
| Fix | Correct the operations (see rejected). |
| Safe to retry | no, change the request first |
| Returned by | apply_landing_page_ops |
#landing_language_single
| Status | 422 |
Class (error_type) | invalid_request |
| Title | One language only |
| Cause | A landing page has exactly one language. |
| Fix | Send one language. |
| Safe to retry | no, change the request first |
| Returned by | apply_landing_page_ops |
#landing_not_publishable
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Landing page not publishable |
| Cause | The checker blocks publishing. |
| Fix | Fix the issues listed in the response. |
| Safe to retry | no, change the request first |
| Returned by | publish_landing_page |
#webhook_url_invalid
| Status | 422 |
Class (error_type) | invalid_request |
| Title | Webhook URL not allowed |
| Cause | The URL is not allowed. Only https, port 443 and no internal networks. |
| Fix | Change the URL. |
| Safe to retry | no, change the request first |
| Returned by | create_webhook_endpoint, update_webhook_endpoint, enable_webhook_endpoint |
#Not found (404, 405, 410)
#not_found
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Not found |
| Cause | This path does not exist. |
| Fix | Check the URL. |
| Safe to retry | no, change the request first |
| Returned by | get_landing_page, apply_landing_page_ops, publish_landing_page, restore_landing_page |
#method_not_allowed
| Status | 405 |
Class (error_type) | invalid_request |
| Title | Method not allowed |
| Cause | This path does not support this HTTP method. |
| Fix | Use a method listed in the 'Allow' header. |
| Safe to retry | no, change the request first |
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Tool not found |
| Cause | This tool does not exist. |
| Fix | Call tools/list for the current tools. |
| Safe to retry | no, change the request first |
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Contact not found |
| Cause | No contact with this ID exists in this account. |
| Fix | Check the ID. Objects of other accounts are reported as not found. |
| Safe to retry | no, change the request first |
| Returned by | get_contact, update_contact, unsubscribe_contact, create_conversation_note, send_text_message, send_template_message |
#template_not_found
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Template not found |
| Cause | No template with this ID exists in this account. |
| Fix | Check the ID. Objects of other accounts are reported as not found. |
| Safe to retry | no, change the request first |
| Returned by | send_template_message, get_template, update_template, create_template_submissions |
#newsletter_not_found
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Newsletter not found |
| Cause | No newsletter with this ID exists in this account. |
| Fix | Check the ID. Objects of other accounts are reported as not found. |
| Safe to retry | no, change the request first |
| Returned by | get_newsletter, update_newsletter, get_newsletter_send_preview, send_newsletter, control_newsletter, send_test_newsletter |
#automation_not_found
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Automation not found |
| Cause | No automation with this ID exists in this account. |
| Fix | Check the ID. Objects of other accounts are reported as not found. |
| Safe to retry | no, change the request first |
| Returned by | get_automation, update_automation, set_automation_status, list_automation_runs, create_automation_run, get_inbound_webhook |
#conversation_not_found
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Conversation not found |
| Cause | No conversation with this ID exists in this account. |
| Fix | Check the ID. Objects of other accounts are reported as not found. |
| Safe to retry | no, change the request first |
| Returned by | get_conversation, update_conversation, create_conversation_note |
#send_not_found
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Send not found |
| Cause | No send with this ID exists in this account. |
| Fix | Check the ID. Objects of other accounts are reported as not found. |
| Safe to retry | no, change the request first |
| Returned by | get_send |
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Media not found |
| Cause | No media file with this ID exists in this account. |
| Fix | Check the ID. Objects of other accounts are reported as not found. |
| Safe to retry | no, change the request first |
#document_not_found
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Document not found |
| Cause | No document with this ID exists in this account. |
| Fix | Check the ID. Objects of other accounts are reported as not found. |
| Safe to retry | no, change the request first |
#answer_not_found
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Answer not found |
| Cause | No learned answer with this ID exists in this account. |
| Fix | Check the ID. Objects of other accounts are reported as not found. |
| Safe to retry | no, change the request first |
| Returned by | update_learned_answer |
#endpoint_not_found
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Endpoint not found |
| Cause | No webhook endpoint with this ID exists in this account. |
| Fix | Check the ID. Objects of other accounts are reported as not found. |
| Safe to retry | no, change the request first |
| Returned by | get_webhook_endpoint, update_webhook_endpoint, unsubscribe_webhook_endpoint, rotate_webhook_secret, enable_webhook_endpoint, test_webhook_endpoint, replay_webhook_events, list_webhook_deliveries |
#delivery_not_found
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Delivery not found |
| Cause | No webhook delivery with this ID exists in this account. |
| Fix | Check the ID. Objects of other accounts are reported as not found. |
| Safe to retry | no, change the request first |
| Returned by | redeliver_webhook_delivery |
#sequence_not_found
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Sequence not found |
| Cause | No follow-up sequence with this ID exists in this account. |
| Fix | Check the ID. Objects of other accounts are reported as not found. |
| Safe to retry | no, change the request first |
| Returned by | get_followup_sequence, update_followup_sequence |
#step_not_found
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Step not found |
| Cause | No follow-up step with this ID exists in this account. |
| Fix | Check the ID. Objects of other accounts are reported as not found. |
| Safe to retry | no, change the request first |
| Returned by | update_followup_sequence, update_followup_settings |
#export_not_found
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Export not found |
| Cause | No export with this ID exists in this account. |
| Fix | Check the ID. Objects of other accounts are reported as not found. |
| Safe to retry | no, change the request first |
| Returned by | get_contact_export |
#plan_not_found
| Status | 404 |
Class (error_type) | invalid_request |
| Title | Plan not found |
| Cause | No plan with this ID exists. |
| Fix | Request a new preview. |
| Safe to retry | no, change the request first |
| Returned by | create_automation_run, create_optin_confirmations, publish_landing_page, create_template_submissions |
#plan_expired
| Status | 410 |
Class (error_type) | invalid_request |
| Title | Plan expired |
| Cause | The plan is older than 10 minutes. |
| Fix | Request a new preview. |
| Safe to retry | no, change the request first |
| Returned by | create_automation_run, create_optin_confirmations, publish_landing_page, create_template_submissions |
#Conflicts (409)
| Status | 409 |
Class (error_type) | conflict |
| Title | Contact already exists |
| Cause | A contact with this phone number or email already exists. |
| Fix | Use PATCH on the existing contact (see existing_id). |
| Safe to retry | no, change the request first |
| Returned by | create_contact, update_contact |
#conflict
| Status | 409 |
Class (error_type) | conflict |
| Title | Conflict |
| Cause | The state of the object does not allow this. |
| Fix | Read the object again. |
| Safe to retry | no, change the request first |
| Returned by | 16 operations |
#newsletter_locked
| Status | 409 |
Class (error_type) | conflict |
| Title | Newsletter locked |
| Cause | The newsletter is scheduled or sent and cannot be changed. |
| Fix | Cancel it first with the control action. |
| Safe to retry | no, change the request first |
| Returned by | update_newsletter, send_newsletter, control_newsletter |
#template_in_use
| Status | 409 |
Class (error_type) | conflict |
| Title | Template in use |
| Cause | The template is used by a newsletter or an automation. |
| Fix | Remove the usage first. |
| Safe to retry | no, change the request first |
#idempotency_in_progress
| Status | 409 |
Class (error_type) | conflict |
| Title | Request in progress |
| Cause | A request with this idempotency key is still running. |
| Fix | Retry after the time in 'Retry-After'. |
| Safe to retry | yes, later |
| Returned by | 32 operations |
#plan_already_used
| Status | 409 |
Class (error_type) | conflict |
| Title | Plan already used |
| Cause | The plan was already used. |
| Fix | Read the result of the first call. |
| Safe to retry | no, change the request first |
| Returned by | create_automation_run, create_optin_confirmations, publish_landing_page, create_template_submissions |
#plan_mismatch
| Status | 409 |
Class (error_type) | conflict |
| Title | Plan does not match |
| Cause | The plan belongs to another account, key, action or request. |
| Fix | Request a new preview. |
| Safe to retry | no, change the request first |
| Returned by | create_automation_run, create_optin_confirmations, publish_landing_page, create_template_submissions |
#plan_changed
| Status | 409 |
Class (error_type) | conflict |
| Title | Plan changed |
| Cause | The content or audience changed after the preview. |
| Fix | Check the new preview in the response and request a new plan. |
| Safe to retry | no, change the request first |
| Returned by | create_automation_run, create_optin_confirmations, publish_landing_page |
#automation_not_active
| Status | 409 |
Class (error_type) | conflict |
| Title | Automation not active |
| Cause | A run needs an active automation. |
| Fix | Set the status to active first. |
| Safe to retry | no, change the request first |
| Returned by | create_automation_run |
#webhook_limit_reached
| Status | 409 |
Class (error_type) | conflict |
| Title | Webhook limit reached |
| Cause | The account has the maximum of 20 webhook endpoints. |
| Fix | Delete old endpoints. |
| Safe to retry | no, change the request first |
| Returned by | create_webhook_endpoint |
#declined_by_user
| Status | 409 |
Class (error_type) | conflict |
| Title | Declined by user |
| Cause | The user declined this action. |
| Fix | Do not repeat the call without a new request from the user. |
| Safe to retry | no, change the request first |
#Payment and limits (402, 429)
#quota_exceeded
| Status | 402 |
Class (error_type) | permission |
| Title | Quota exceeded |
| Cause | The monthly message quota is used up. |
| Fix | Check the plan and quota. |
| Safe to retry | no, change the request first |
| Returned by | create_automation, set_automation_status, create_contact, send_newsletter, control_newsletter, send_text_message, send_template_message |
#insufficient_credits
| Status | 402 |
Class (error_type) | permission |
| Title | Insufficient credits |
| Cause | The credits are not enough. |
| Fix | Add credits in the app. |
| Safe to retry | no, change the request first |
| Returned by | send_newsletter, control_newsletter |
#daily_limit_reached
| Status | 429 |
Class (error_type) | rate_limit |
| Title | Daily limit reached (not used) |
| Cause | Not used. An API key has no daily limit, so this code is never returned. It is only kept for old clients. |
| Fix | Nothing to do. Wait for the time in 'Retry-After' if you see 429 rate_limited. |
| Safe to retry | yes, later |
#rate_limited
| Status | 429 |
Class (error_type) | rate_limit |
| Title | Too many requests |
| Cause | Too many requests. Wait and try again. |
| Fix | Wait for the time in 'Retry-After'. |
| Safe to retry | yes, later |
| Returned by | 82 operations |
#Problems on the other side or on ours (5xx)
#not_available
| Status | 501 |
Class (error_type) | api |
| Title | Not available |
| Cause | This function is not active in this release. |
| Fix | Try again later. |
| Safe to retry | no, change the request first |
| Returned by | create_followup_sequence, update_followup_sequence |
#suppression_check_unavailable
| Status | 503 |
Class (error_type) | api |
| Title | Suppression check unavailable |
| Cause | The suppression list cannot be read, so nothing was sent. |
| Fix | Try again later. |
| Safe to retry | yes, later |
| Returned by | send_newsletter, control_newsletter, send_test_newsletter, send_text_message, send_template_message |
#upstream_error
| Status | 502 |
Class (error_type) | api |
| Title | Upstream error |
| Cause | A connected service (for example WhatsApp) reported an error. |
| Fix | Read the status first (GET /sends/{id}). Use a new Idempotency-Key only if nothing was sent. |
| Safe to retry | yes, later |
| Returned by | send_newsletter, control_newsletter, send_test_newsletter, send_text_message, send_template_message, create_template_submissions |
#service_unavailable
| Status | 503 |
Class (error_type) | api |
| Title | Service unavailable |
| Cause | The service is temporarily unavailable. |
| Fix | Try again later. |
| Safe to retry | yes, later |
| Returned by | 42 operations |
#internal_error
| Status | 500 |
Class (error_type) | api |
| Title | Internal error |
| Cause | Something went wrong on our side. |
| Fix | Contact support and give the request ID. |
| Safe to retry | yes, later |
| Returned by | 82 operations |