smartchat

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

Status401
Class (error_type)authentication
TitleAuthentication required
CauseNo API key was sent. Send 'Authorization: Bearer <key>'.
FixSend the header 'Authorization: Bearer <key>'.
Safe to retryno, change the request first
Returned by82 operations

#api_key_invalid

Status401
Class (error_type)authentication
TitleInvalid API key
CauseThis API key is not valid.
FixCheck the key.
Safe to retryno, change the request first
Returned by82 operations

#api_key_revoked

Status401
Class (error_type)authentication
TitleAPI key revoked
CauseThis API key was revoked.
FixCreate a new key in the app.
Safe to retryno, change the request first
Returned by82 operations

#api_key_expired

Status401
Class (error_type)authentication
TitleAPI key expired
CauseThis API key has expired.
FixCreate a new key in the app.
Safe to retryno, change the request first
Returned by82 operations

#insufficient_scope

Status403
Class (error_type)permission
TitleMissing permission
CauseThis key lacks a required permission.
FixAdd the permission to the key (create a new key).
Safe to retryno, change the request first
Returned by81 operations

#ip_not_allowed

Status403
Class (error_type)permission
TitleIP address not allowed
CauseThis IP address is not allowed for this key.
FixChange the IP list of the key.
Safe to retryno, change the request first
Returned by82 operations

#action_not_allowed

Status403
Class (error_type)permission
TitleAction not allowed with API keys
CauseThis 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.
FixDo this in the app.
Safe to retryno, change the request first

#account_blocked

Status403
Class (error_type)permission
TitleAccount blocked
CauseThis account is blocked.
FixContact support.
Safe to retryno, change the request first
Returned by41 operations

#subscription_locked

Status403
Class (error_type)permission
TitleSubscription locked
CauseThe subscription or payment state blocks this function.
FixCheck the subscription in the app.
Safe to retryno, change the request first
Returned bycreate_optin_confirmations, send_newsletter, control_newsletter, send_test_newsletter, send_text_message, send_template_message

#feature_unavailable

Status403
Class (error_type)permission
TitleFunction not in plan
CauseThis function is not included in the current plan.
FixCheck the plan in the app.
Safe to retryno, change the request first
Returned byupdate_ai_reply_settings, create_automation, set_automation_status, create_media

#Input (400, 413, 415, 422)

#bad_request

Status400
Class (error_type)invalid_request
TitleBad request
CauseThe request could not be read.
FixCheck the request body (valid JSON).
Safe to retryno, change the request first
Returned by20 operations

#validation_failed

Status422
Class (error_type)invalid_request
TitleValidation failed
CauseA field is not valid.
FixCorrect the input.
Safe to retryno, change the request first
Returned by74 operations

#missing_parameter

Status400
Class (error_type)invalid_request
TitleMissing parameter
CauseA required field is missing.
FixAdd the field.
Safe to retryno, change the request first
Returned by27 operations

#unknown_parameter

Status400
Class (error_type)invalid_request
TitleUnknown parameter
CauseA field is not known.
FixRemove the field.
Safe to retryno, change the request first
Returned by34 operations

#invalid_cursor

Status400
Class (error_type)invalid_request
TitleInvalid cursor
CauseThe cursor is expired, forged or belongs to other filters.
FixStart again without a cursor.
Safe to retryno, change the request first
Returned by19 operations

#invalid_phone_number

Status422
Class (error_type)invalid_request
TitleInvalid phone number
CauseThe phone number is not valid E.164.
FixSend the number with country code, for example +4915112345678.
Safe to retryno, change the request first
Returned byupdate_business_profile, create_contact, update_contact, send_test_newsletter

#invalid_email

Status422
Class (error_type)invalid_request
TitleInvalid email address
CauseThe email address is not valid.
FixCorrect the address.
Safe to retryno, change the request first
Returned bycreate_contact, update_contact

#payload_too_large

Status413
Class (error_type)invalid_request
TitlePayload too large
CauseThe request body or file is too large.
FixSend less data (limits are listed per route in the docs).
Safe to retryno, change the request first
Returned bycreate_media

#unsupported_media_type

Status415
Class (error_type)invalid_request
TitleUnsupported media type
CauseThis content type or file type is not allowed.
FixUse an allowed type.
Safe to retryno, change the request first
Returned bycreate_media

#idempotency_key_required

Status400
Class (error_type)invalid_request
TitleIdempotency key required
CauseThis call needs an 'Idempotency-Key' header.
FixSend the 'Idempotency-Key' header.
Safe to retryno, change the request first
Returned by23 operations

#idempotency_key_invalid

Status400
Class (error_type)invalid_request
TitleInvalid idempotency key
CauseThe 'Idempotency-Key' header must be 1 to 255 visible ASCII characters.
FixUse 1 to 255 visible ASCII characters, for example a UUID.
Safe to retryno, change the request first
Returned by32 operations

#idempotency_key_reused

Status422
Class (error_type)invalid_request
TitleIdempotency key reused
CauseThis idempotency key was already used with a different request.
FixUse a new key.
Safe to retryno, change the request first
Returned by32 operations

#plan_required

Status400
Class (error_type)invalid_request
TitlePlan required
CauseThis action needs a plan_id from a preview.
FixRequest the preview first.
Safe to retryno, change the request first
Returned bycreate_automation_run, publish_landing_page, create_template_submissions

#contact_not_confirmed

Status422
Class (error_type)invalid_request
TitleContact not confirmed
CauseThe contact has no confirmed opt-in.
FixGet the confirmation first.
Safe to retryno, change the request first
Returned byunsubscribe_contact, send_text_message, send_template_message

#contact_opted_out

Status422
Class (error_type)invalid_request
TitleContact opted out
CauseThe contact has unsubscribed.
FixNever send to this contact.
Safe to retryno, change the request first
Returned bysend_test_newsletter, send_text_message, send_template_message

#number_suppressed

Status422
Class (error_type)invalid_request
TitleNumber suppressed
CauseThe number is on the suppression list.
FixNever send to this number.
Safe to retryno, change the request first
Returned bysend_test_newsletter, send_text_message, send_template_message

#window_closed

Status422
Class (error_type)invalid_request
Title24-hour window closed
CauseThe 24-hour window is closed. Free text is not possible.
FixSend an approved template instead.
Safe to retryno, change the request first
Returned bysend_text_message

#template_not_approved

Status422
Class (error_type)invalid_request
TitleTemplate not approved
CauseThe template is not approved.
FixCheck the template status.
Safe to retryno, change the request first
Returned bycreate_optin_confirmations, send_newsletter, control_newsletter, send_test_newsletter, send_template_message

#template_variables_missing

Status422
Class (error_type)invalid_request
TitleTemplate variables missing
CauseValues for some template variables are missing.
FixAdd the missing values.
Safe to retryno, change the request first
Returned bysend_template_message

#template_rejected

Status422
Class (error_type)invalid_request
TitleTemplate rejected
CauseWhatsApp rejected the template.
FixChange the text and submit again.
Safe to retryno, change the request first
Returned bysend_newsletter, control_newsletter, create_template, update_template

#whatsapp_not_connected

Status422
Class (error_type)invalid_request
TitleWhatsApp not connected
CauseNo WhatsApp number is connected.
FixConnect a number in the app.
Safe to retryno, change the request first
Returned bysend_newsletter, control_newsletter, send_test_newsletter, send_text_message, send_template_message, create_template_submissions

#test_phone_not_set

Status422
Class (error_type)invalid_request
TitleTest number not set
CauseThe account has no test number.
FixSet the test number in the profile.
Safe to retryno, change the request first
Returned bysend_test_newsletter

#test_phone_unverified

Status422
Class (error_type)invalid_request
TitleTest number not verified
CauseThe test number is not verified.
FixVerify the test number in the app.
Safe to retryno, change the request first

#recipient_limit_exceeded

Status422
Class (error_type)invalid_request
TitleToo many recipients
CauseThe call has more recipients than allowed.
FixMake the audience smaller.
Safe to retryno, change the request first

#audience_empty

Status422
Class (error_type)invalid_request
TitleAudience empty
CauseThe audience has no reachable contacts.
FixCheck the audience.
Safe to retryno, change the request first
Returned bycreate_optin_confirmations, send_newsletter, control_newsletter

#automation_invalid

Status422
Class (error_type)invalid_request
TitleAutomation invalid
CauseThe automation spec breaks a catalog rule.
FixCorrect the spec (see errors).
Safe to retryno, change the request first
Returned bycreate_automation, update_automation, set_automation_status

#landing_ops_rejected

Status422
Class (error_type)invalid_request
TitleOperations rejected
CauseSome operations were rejected. Nothing was changed.
FixCorrect the operations (see rejected).
Safe to retryno, change the request first
Returned byapply_landing_page_ops

#landing_language_single

Status422
Class (error_type)invalid_request
TitleOne language only
CauseA landing page has exactly one language.
FixSend one language.
Safe to retryno, change the request first
Returned byapply_landing_page_ops

#landing_not_publishable

Status422
Class (error_type)invalid_request
TitleLanding page not publishable
CauseThe checker blocks publishing.
FixFix the issues listed in the response.
Safe to retryno, change the request first
Returned bypublish_landing_page

#webhook_url_invalid

Status422
Class (error_type)invalid_request
TitleWebhook URL not allowed
CauseThe URL is not allowed. Only https, port 443 and no internal networks.
FixChange the URL.
Safe to retryno, change the request first
Returned bycreate_webhook_endpoint, update_webhook_endpoint, enable_webhook_endpoint

#Not found (404, 405, 410)

#not_found

Status404
Class (error_type)invalid_request
TitleNot found
CauseThis path does not exist.
FixCheck the URL.
Safe to retryno, change the request first
Returned byget_landing_page, apply_landing_page_ops, publish_landing_page, restore_landing_page

#method_not_allowed

Status405
Class (error_type)invalid_request
TitleMethod not allowed
CauseThis path does not support this HTTP method.
FixUse a method listed in the 'Allow' header.
Safe to retryno, change the request first

#tool_not_found

Status404
Class (error_type)invalid_request
TitleTool not found
CauseThis tool does not exist.
FixCall tools/list for the current tools.
Safe to retryno, change the request first

#contact_not_found

Status404
Class (error_type)invalid_request
TitleContact not found
CauseNo contact with this ID exists in this account.
FixCheck the ID. Objects of other accounts are reported as not found.
Safe to retryno, change the request first
Returned byget_contact, update_contact, unsubscribe_contact, create_conversation_note, send_text_message, send_template_message

#template_not_found

Status404
Class (error_type)invalid_request
TitleTemplate not found
CauseNo template with this ID exists in this account.
FixCheck the ID. Objects of other accounts are reported as not found.
Safe to retryno, change the request first
Returned bysend_template_message, get_template, update_template, create_template_submissions

#newsletter_not_found

Status404
Class (error_type)invalid_request
TitleNewsletter not found
CauseNo newsletter with this ID exists in this account.
FixCheck the ID. Objects of other accounts are reported as not found.
Safe to retryno, change the request first
Returned byget_newsletter, update_newsletter, get_newsletter_send_preview, send_newsletter, control_newsletter, send_test_newsletter

#automation_not_found

Status404
Class (error_type)invalid_request
TitleAutomation not found
CauseNo automation with this ID exists in this account.
FixCheck the ID. Objects of other accounts are reported as not found.
Safe to retryno, change the request first
Returned byget_automation, update_automation, set_automation_status, list_automation_runs, create_automation_run, get_inbound_webhook

#conversation_not_found

Status404
Class (error_type)invalid_request
TitleConversation not found
CauseNo conversation with this ID exists in this account.
FixCheck the ID. Objects of other accounts are reported as not found.
Safe to retryno, change the request first
Returned byget_conversation, update_conversation, create_conversation_note

#send_not_found

Status404
Class (error_type)invalid_request
TitleSend not found
CauseNo send with this ID exists in this account.
FixCheck the ID. Objects of other accounts are reported as not found.
Safe to retryno, change the request first
Returned byget_send

#media_not_found

Status404
Class (error_type)invalid_request
TitleMedia not found
CauseNo media file with this ID exists in this account.
FixCheck the ID. Objects of other accounts are reported as not found.
Safe to retryno, change the request first

#document_not_found

Status404
Class (error_type)invalid_request
TitleDocument not found
CauseNo document with this ID exists in this account.
FixCheck the ID. Objects of other accounts are reported as not found.
Safe to retryno, change the request first

#answer_not_found

Status404
Class (error_type)invalid_request
TitleAnswer not found
CauseNo learned answer with this ID exists in this account.
FixCheck the ID. Objects of other accounts are reported as not found.
Safe to retryno, change the request first
Returned byupdate_learned_answer

#endpoint_not_found

Status404
Class (error_type)invalid_request
TitleEndpoint not found
CauseNo webhook endpoint with this ID exists in this account.
FixCheck the ID. Objects of other accounts are reported as not found.
Safe to retryno, change the request first
Returned byget_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

Status404
Class (error_type)invalid_request
TitleDelivery not found
CauseNo webhook delivery with this ID exists in this account.
FixCheck the ID. Objects of other accounts are reported as not found.
Safe to retryno, change the request first
Returned byredeliver_webhook_delivery

#sequence_not_found

Status404
Class (error_type)invalid_request
TitleSequence not found
CauseNo follow-up sequence with this ID exists in this account.
FixCheck the ID. Objects of other accounts are reported as not found.
Safe to retryno, change the request first
Returned byget_followup_sequence, update_followup_sequence

#step_not_found

Status404
Class (error_type)invalid_request
TitleStep not found
CauseNo follow-up step with this ID exists in this account.
FixCheck the ID. Objects of other accounts are reported as not found.
Safe to retryno, change the request first
Returned byupdate_followup_sequence, update_followup_settings

#export_not_found

Status404
Class (error_type)invalid_request
TitleExport not found
CauseNo export with this ID exists in this account.
FixCheck the ID. Objects of other accounts are reported as not found.
Safe to retryno, change the request first
Returned byget_contact_export

#plan_not_found

Status404
Class (error_type)invalid_request
TitlePlan not found
CauseNo plan with this ID exists.
FixRequest a new preview.
Safe to retryno, change the request first
Returned bycreate_automation_run, create_optin_confirmations, publish_landing_page, create_template_submissions

#plan_expired

Status410
Class (error_type)invalid_request
TitlePlan expired
CauseThe plan is older than 10 minutes.
FixRequest a new preview.
Safe to retryno, change the request first
Returned bycreate_automation_run, create_optin_confirmations, publish_landing_page, create_template_submissions

#Conflicts (409)

#contact_already_exists

Status409
Class (error_type)conflict
TitleContact already exists
CauseA contact with this phone number or email already exists.
FixUse PATCH on the existing contact (see existing_id).
Safe to retryno, change the request first
Returned bycreate_contact, update_contact

#conflict

Status409
Class (error_type)conflict
TitleConflict
CauseThe state of the object does not allow this.
FixRead the object again.
Safe to retryno, change the request first
Returned by16 operations

#newsletter_locked

Status409
Class (error_type)conflict
TitleNewsletter locked
CauseThe newsletter is scheduled or sent and cannot be changed.
FixCancel it first with the control action.
Safe to retryno, change the request first
Returned byupdate_newsletter, send_newsletter, control_newsletter

#template_in_use

Status409
Class (error_type)conflict
TitleTemplate in use
CauseThe template is used by a newsletter or an automation.
FixRemove the usage first.
Safe to retryno, change the request first

#idempotency_in_progress

Status409
Class (error_type)conflict
TitleRequest in progress
CauseA request with this idempotency key is still running.
FixRetry after the time in 'Retry-After'.
Safe to retryyes, later
Returned by32 operations

#plan_already_used

Status409
Class (error_type)conflict
TitlePlan already used
CauseThe plan was already used.
FixRead the result of the first call.
Safe to retryno, change the request first
Returned bycreate_automation_run, create_optin_confirmations, publish_landing_page, create_template_submissions

#plan_mismatch

Status409
Class (error_type)conflict
TitlePlan does not match
CauseThe plan belongs to another account, key, action or request.
FixRequest a new preview.
Safe to retryno, change the request first
Returned bycreate_automation_run, create_optin_confirmations, publish_landing_page, create_template_submissions

#plan_changed

Status409
Class (error_type)conflict
TitlePlan changed
CauseThe content or audience changed after the preview.
FixCheck the new preview in the response and request a new plan.
Safe to retryno, change the request first
Returned bycreate_automation_run, create_optin_confirmations, publish_landing_page

#automation_not_active

Status409
Class (error_type)conflict
TitleAutomation not active
CauseA run needs an active automation.
FixSet the status to active first.
Safe to retryno, change the request first
Returned bycreate_automation_run

#webhook_limit_reached

Status409
Class (error_type)conflict
TitleWebhook limit reached
CauseThe account has the maximum of 20 webhook endpoints.
FixDelete old endpoints.
Safe to retryno, change the request first
Returned bycreate_webhook_endpoint

#declined_by_user

Status409
Class (error_type)conflict
TitleDeclined by user
CauseThe user declined this action.
FixDo not repeat the call without a new request from the user.
Safe to retryno, change the request first

#Payment and limits (402, 429)

#quota_exceeded

Status402
Class (error_type)permission
TitleQuota exceeded
CauseThe monthly message quota is used up.
FixCheck the plan and quota.
Safe to retryno, change the request first
Returned bycreate_automation, set_automation_status, create_contact, send_newsletter, control_newsletter, send_text_message, send_template_message

#insufficient_credits

Status402
Class (error_type)permission
TitleInsufficient credits
CauseThe credits are not enough.
FixAdd credits in the app.
Safe to retryno, change the request first
Returned bysend_newsletter, control_newsletter

#daily_limit_reached

Status429
Class (error_type)rate_limit
TitleDaily limit reached (not used)
CauseNot used. An API key has no daily limit, so this code is never returned. It is only kept for old clients.
FixNothing to do. Wait for the time in 'Retry-After' if you see 429 rate_limited.
Safe to retryyes, later

#rate_limited

Status429
Class (error_type)rate_limit
TitleToo many requests
CauseToo many requests. Wait and try again.
FixWait for the time in 'Retry-After'.
Safe to retryyes, later
Returned by82 operations

#Problems on the other side or on ours (5xx)

#not_available

Status501
Class (error_type)api
TitleNot available
CauseThis function is not active in this release.
FixTry again later.
Safe to retryno, change the request first
Returned bycreate_followup_sequence, update_followup_sequence

#suppression_check_unavailable

Status503
Class (error_type)api
TitleSuppression check unavailable
CauseThe suppression list cannot be read, so nothing was sent.
FixTry again later.
Safe to retryyes, later
Returned bysend_newsletter, control_newsletter, send_test_newsletter, send_text_message, send_template_message

#upstream_error

Status502
Class (error_type)api
TitleUpstream error
CauseA connected service (for example WhatsApp) reported an error.
FixRead the status first (GET /sends/{id}). Use a new Idempotency-Key only if nothing was sent.
Safe to retryyes, later
Returned bysend_newsletter, control_newsletter, send_test_newsletter, send_text_message, send_template_message, create_template_submissions

#service_unavailable

Status503
Class (error_type)api
TitleService unavailable
CauseThe service is temporarily unavailable.
FixTry again later.
Safe to retryyes, later
Returned by42 operations

#internal_error

Status500
Class (error_type)api
TitleInternal error
CauseSomething went wrong on our side.
FixContact support and give the request ID.
Safe to retryyes, later
Returned by82 operations