Errors

Errors are RFC 9457 Problem Details, sent as application/problem+json:

{
  "type": "https://docs.nexafone.so/errors/validation_failed",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "validation_failed",
  "detail": "The request is invalid.",
  "requestId": "01J9Z8Q4TQ3W6M5V2X7Y8Z9A0B",
  "errors": [{ "location": "body.name", "message": "expected length >= 1", "value": "" }]
}

Field
code	A stable, machine-readable code: branch on this
type	A link to the code’s page in these docs
status, title	The HTTP status and its text
detail	A human-readable explanation of this occurrence; it may change, so never parse it
requestId	Quote it to support; also in the X-Request-Id header
errors	For validation errors, one entry per problem with location, message and the rejected value

A 5xx never contains internal details. Retry 429, 502, 503 and 504 with backoff (a 429 says how long in Retry-After); fix the request for other 4xx codes.

Catalog

Every code the API can answer with, read from the backend’s source when the docs are built:

General

Code	Status	Meaning
bad_request	400	The request is malformed, such as invalid JSON or a bad Idempotency-Key header.
client_closed_request	499	The request was cancelled.
conflict	409	The request conflicts with the current state, such as a duplicate name.
dashboard_sign_in_required	403	Sign in to the dashboard to make this change.
forbidden	403	The credential is valid but may not do this: a secret key’s scopes or a member’s role lack the operation’s permission, or an IP allow-list or origin check refused the request.
idempotency_in_flight	409	A request with the same Idempotency-Key is still running.
idempotency_key_reused	422	The Idempotency-Key was already used for a different request body or operation.
internal	500	Something failed on Nexafon’s side.
method_not_allowed	405	This endpoint does not support the request method.
not_acceptable	406
not_found	404	Nothing with that id exists in this workspace.
payload_too_large	413	The request body is too large.
precondition_failed	412
rate_limited	429	Too many requests for this IP address, user or API key.
reauthentication_required	401	Sign in again to continue.
test_mode_live	403	Test keys and test SDK sessions cannot call Meta for a live WhatsApp number (messages, WhatsApp calls, templates, number and catalog changes) or move money (payments, subscriptions, wallet settings).
timeout	504	The operation ran out of time.
unauthenticated	401	The Authorization header is missing, or its key or token is unknown, revoked or of the wrong kind.
unavailable	503	A dependency is briefly unavailable.
unsupported_media_type	415
validation_failed	422	The request does not match the operation’s schema or rules.

WhatsApp (from Meta)

Code	Status	Meaning
whatsapp.account_restricted	422	The WhatsApp Business Account is locked or failed verification.
whatsapp.auth_failed	502	WhatsApp no longer accepts this connection’s access token. Reconnect WhatsApp.
whatsapp.bad_response	502	WhatsApp sent a response Nexafon could not read.
whatsapp.business_call_limit	429	This number reached the daily limit of connected business-initiated calls.
whatsapp.call_already_ongoing	409	A call with this contact is already in progress.
whatsapp.call_concurrency_limit	429	This number has too many calls in progress. Try again when one ends.
whatsapp.call_connection_failed	502, 504	WhatsApp could not connect the call. Try again.
whatsapp.call_country_unsupported	422	Business-initiated WhatsApp calls are not available for this number’s country.
whatsapp.call_media_failed	502	The call lost its audio: media could not be sent in time.
whatsapp.call_permission_already_permanent	409	This contact already allows calls permanently, so no request is needed.
whatsapp.call_permission_lookup_limit	429	Too many call permission checks for this contact. Try again later.
whatsapp.call_permission_missing	422	This contact has not allowed calls from your business. Send a call permission request first.
whatsapp.call_permission_request_limit	429	You have sent this contact the most call permission requests allowed for now. Try again after the limit resets.
whatsapp.call_rate_limited	429	This number is placing calls too quickly. Wait before calling again.
whatsapp.call_receiver_uncallable	422	This contact cannot receive WhatsApp calls right now.
whatsapp.call_setup_failed	502	WhatsApp could not set up the call. Try again.
whatsapp.call_sip_number	422	Calls on this number are handled over SIP, not the Calling API.
whatsapp.calling_cannot_be_enabled	422	Calling can only be turned on for numbers with a messaging limit of at least 2,000.
whatsapp.calling_disabled_low_quality	422	WhatsApp paused calling on this number for low quality. Try again when the restriction lifts.
whatsapp.calling_not_enabled	422	Calling is not turned on for this WhatsApp number.
whatsapp.calling_prerequisites_missing	422	Calling cannot be turned on until the number is subscribed to call webhooks.
whatsapp.country_restricted	422	This WhatsApp Business Account may not message contacts in this country.
whatsapp.deletion_pending	409	This number was deleted recently. Wait 5 minutes before registering it.
whatsapp.deregistration_failed	422	A previous deregistration of this number failed. Deregister it again first.
whatsapp.display_name_not_approved	422	This number’s display name is not approved yet, so it cannot send messages.
whatsapp.ecosystem_limited	422	WhatsApp did not deliver this marketing message to protect the contact’s experience.
whatsapp.experiment_excluded	422	WhatsApp held this marketing message back as part of an experiment.
whatsapp.flow_blocked	422	The WhatsApp Flow in this message is blocked.
whatsapp.flow_throttled	429	The WhatsApp Flow in this message hit its hourly limit.
whatsapp.invalid_input	422
whatsapp.invalid_parameter	422	The request to WhatsApp is missing a required value.
whatsapp.marketing_disabled	422	Marketing templates are turned off for this WhatsApp Business Account.
whatsapp.media_download_failed	422	WhatsApp could not download the contact’s media.
whatsapp.media_too_large	413	The media is larger than the … MB Nexafon accepts.
whatsapp.media_upload_failed	422	WhatsApp could not fetch or accept the media. Check its type, size and link.
whatsapp.messaging_limit	429	This number reached its messaging limit after quality issues.
whatsapp.no_call_id	502	WhatsApp did not return an ID for the new call.
whatsapp.not_found	404	WhatsApp could not find that item.
whatsapp.payment_required	422	WhatsApp calls need a valid payment method on the WhatsApp Business Account.
whatsapp.permission_missing	502	The WhatsApp connection is missing a permission this action needs. Reconnect WhatsApp.
whatsapp.phone_not_registered	422	This WhatsApp number is not registered with the Cloud API.
whatsapp.phone_number_deleted	422	This WhatsApp number has been deleted from the WhatsApp Business Account.
whatsapp.rate_limited	429	The WhatsApp Business Account reached its request limit. Try again later.
whatsapp.recipient_blocked	422	This contact is blocked on WhatsApp by your business.
whatsapp.recipient_not_allowed	422	That number is not on the test number’s allowed recipient list. Add it in WhatsApp Manager first.
whatsapp.recipient_opted_out	422	This contact has stopped marketing messages from your business.
whatsapp.recipient_throttled	429	Too many messages to this contact in a short time. Wait before sending more.
whatsapp.recipient_undeliverable	422	That number cannot receive WhatsApp messages. Check it is correct and has an up-to-date WhatsApp installed.
whatsapp.reengagement_required	422	More than 24 hours have passed since the contact last wrote. Send an approved template instead.
whatsapp.registration_throttled	429	Too many registration attempts for this number. Try again later.
whatsapp.rejected	422, 502	WhatsApp could not process the request.
whatsapp.same_sender_recipient	422	A business number cannot message itself.
whatsapp.spam_limited	429	WhatsApp limited sending because too many recent messages were blocked or reported.
whatsapp.template_disabled	422	WhatsApp disabled this template after repeated quality pauses.
whatsapp.template_field_too_long	422	A template field is longer than WhatsApp allows.
whatsapp.template_format_invalid	422	The template body is not formatted the way WhatsApp requires.
whatsapp.template_limit	422	This WhatsApp Business Account has reached its template limit.
whatsapp.template_not_found	422	That template does not exist or is not approved in this language.
whatsapp.template_param_format	422	A template variable has the wrong format.
whatsapp.template_param_invalid	422	WhatsApp rejected one of the template’s variables.
whatsapp.template_param_mismatch	422	The template’s variables do not match what the template expects.
whatsapp.template_param_placement	422	Template variables cannot be at the very start or end of the text.
whatsapp.template_paused	422	WhatsApp paused this template for low quality.
whatsapp.template_policy_violation	422	The template’s content breaks WhatsApp policy.
whatsapp.template_status_locked	422	This template’s status cannot be changed right now.
whatsapp.template_text_too_long	422	The template text is too long once its variables are filled in.
whatsapp.template_too_many_params	422	The template has too many variables for its length.
whatsapp.throughput_limited	429	WhatsApp is sending as fast as this number allows. Try again in a moment.
whatsapp.timeout	504	WhatsApp did not answer in time. Try again.
whatsapp.token_expired	502	The WhatsApp access token has expired. Reconnect WhatsApp.
whatsapp.too_many_pin_attempts	429	The PIN was entered too quickly. Wait a moment and try again.
whatsapp.unavailable	502, 503	The WhatsApp Business Account is in maintenance. Try again later.
whatsapp.unreachable	502	Could not reach WhatsApp. Try again.
whatsapp.unsupported_message_type	422	That number cannot receive this type of message.
whatsapp.verification_required	422	This number must be verified before it can be registered.
whatsapp.wrong_pin	422	The two-step verification PIN is wrong.

Keys and SDK sessions

Code	Status	Meaning
api_key_limit	409	A workspace can have … active API keys. Revoke one you no longer use first.
client_not_allowed	403	The page’s origin (or the app’s bundle id or package name) is not on the publishable key’s list.
feature_not_in_plan	403	The workspace’s plan does not include the feature the operation declares (x-feature in the API reference).
invalid_publishable_key	401	The publishable key is unknown or revoked, or the workspace or partner cannot use it.
invalid_user_token	401	The user token is not a valid HS256 JWT signed with one of the workspace’s (or partner’s) secret keys of the same mode as the publishable key, or a required claim (sub, jti, exp) is missing.
last_owner	409	A workspace needs at least one owner. Make someone else an owner first.
no_free_seat	403	The store has no free seat for a new member.
partner_key_limit	409	A partner can have … active keys. Revoke one it no longer uses first.
partner_store_unknown	403	The partner user token lists an externalRef that is not one of the partner’s stores.
partner_suspended	403	The partner is suspended, so its keys, sessions and stores’ embeds are refused until Nexafon reactivates it.
sdk_email_not_verified	422	The user token needs email_verified set to true the first time this user signs in: the email is how the user is matched to a member.
sdk_email_required	422	The user token needs an email claim, with email_verified set to true, the first time this user signs in.
sdk_member_disabled	403	The user’s membership was disabled.
sdk_member_not_found	403	No member of the workspace has the token’s email, and the workspace does not add SDK users automatically.
sdk_role_not_allowed	403	New SDK users can be given … or a role below it.
sdk_session_expired	401	The SDK session passed its refreshUntil.
user_token_expired	401	The token’s exp has passed, or lies more than 10 minutes ahead.
user_token_replayed	401	Each user token works once (its jti is remembered).

Partners

Code	Status	Meaning
partner_plan_unavailable	409	The partner’s default store plan has no published version. Ask Nexafon to publish it.

Commerce

Code	Status	Meaning
coupon_code_taken	409	Another promotion already uses this coupon code.
order_status_not_allowed	409	Only a delivery order goes out for delivery.
plan_limit_reached	403	A limit of the workspace’s plan is reached.
promotion_in_use	409	A promotion uses this number list. Change or delete that promotion first.
promotion_name_taken	409	A number list with this name already exists.
retailer_id_taken	409	A retailer id is already used by another product of the store.
whatsapp_flow_decrypt_failed	421	The request cannot be decrypted with the business key.
whatsapp_flow_not_published	409	This WhatsApp Flow is not published on the business number yet. Try again in a few minutes.
whatsapp_flow_signature_invalid	432	The request signature is missing or does not match the body.
whatsapp_flow_token_invalid	427

Billing

Code	Status	Meaning
addon_not_offered	409	The plan you move to at the renewal does not offer this add-on.
approver_is_author	403	You asked for this …, so someone else has to approve or reject it.
approver_is_requester	403	You asked for this correction, so someone else must decide it.
billing_past_due	402	Billing is past due, so calls to customers are paused until the invoice is paid. Customers can still call you.
billing_unavailable	503	Billing can’t check the balance right now, so paid messages and calls are paused. Try again in a moment.
credit_limit_reached	402	This workspace has used its credit limit, so calls to customers are paused. Customers can still call you.
insufficient_balance	402	The prepaid wallet cannot cover the charge.
invoice_pdf_pending	409	The invoice PDF is still being prepared. Try again in a minute.
payer_numbers_limited	429	This workspace already asked … new numbers to approve a payment today. Pay from a number that paid before, or try again tomorrow.
rates_missing	503	This can’t be priced because no Meta rate is loaded for it yet. Ask Nexafon support to load the rate card.
seat_limit_reached	403	Every seat of the plan is taken.
use_seats_endpoint	409	This add-on is the extra seats of the workspace’s subscription. Change the subscription’s seats instead.

Calls, meetings and recordings

Code	Status	Meaning
already_in_call	409	This person is already ringing or in the call.
bad_offer	422	The device’s SDP offer cannot be answered.
call_already_answered	409	Someone else answered this call.
call_answered_on_other_device	409	You answered this call on another device.
call_back_unavailable	409	Only a staff call that rang you and that you did not answer can be called back.
call_not_ringing	409	This call is not ringing for you.
call_over	409	This call has ended.
call_permission_already_granted	409	This customer already allows your calls permanently.
call_permission_missing	409	The customer has not allowed calls from the business.
call_permission_request_limit	429	WhatsApp allows one call permission request a day and two a week per customer until a call connects.
call_permission_template_missing	422	More than 24 hours have passed since the customer last wrote, so only an approved template with a call permission button can ask them. Create one under Templates.
call_recording_consent_missing	409	Pick the recording announcement in the WhatsApp call settings before recording calls.
call_recording_not_in_plan	403	Your workspace’s plan does not include call recording.
media_unavailable	409, 503	Calls cannot connect right now. Try again in a moment.
meeting_cancelled	409	This meeting was cancelled.
meeting_not_open	409	This meeting has not started.
meeting_over	409	This meeting is over.
no_transfer	409	No warm transfer is in progress on this call.
not_a_whatsapp_call	409	This is not a WhatsApp call.
not_in_call	409	Only someone in the call can do this.
queue_empty	409	Nobody is waiting in your queues right now.
recording_in_use	409	This recording is in use. Pick another recording in the places listed, then delete it.
recording_not_ready	409	This recording has no audio yet. Wait until it is ready.
transfer_in_progress	409	Finish or cancel the transfer in progress first.
whatsapp_call_country_unsupported	422	WhatsApp does not offer calls to customers from business numbers in …. Customers can still call you.
whatsapp_call_max_duration	409	Calls to customers end after … minutes, so this call was ended.
whatsapp_call_not_connected	409	This call is not connected to the customer.
whatsapp_calling_off	409	Calling is not turned on for this WhatsApp number.
whatsapp_calls_unavailable	503	WhatsApp calls are not available on this server.
whatsapp_number_disconnected	409	Connect the business WhatsApp number before calling customers.

Messaging and templates

Code	Status	Meaning
client_msg_id_reused	409	This clientMsgId was already used for another message. Use a new id for each message.
message_not_sent	409	Only messages that reached WhatsApp can get a reaction.
template_busy	409	This template is still being sent to WhatsApp. Try again in a moment.
template_exists	409	A template with this name already exists in this language. Pick another name, or edit that template.
template_not_approved	422
template_not_editable	409
test_mode_live_number	403	Test keys and test SDK sessions never message real customers.
whatsapp_byo_keys_off	403	Connecting with your own keys is not offered. Connect the number with Meta’s signup instead.
whatsapp_calling_not_changed	502	Meta did not change calling for this number. Check the number in WhatsApp Manager and try again.
whatsapp_number_limit	409	This workspace already has a WhatsApp number. Each business connects one number; routing sends customers to teams.
whatsapp_number_missing	409	Connect the business WhatsApp number before managing templates.
whatsapp_number_not_in_account	422	This phone number is not in that WhatsApp Business Account. Check the IDs in Meta’s WhatsApp Manager.
whatsapp_number_not_included	403	Your plan does not include a WhatsApp number.
whatsapp_number_not_onboarded	409	Nexafon has no Meta access for this number, so it cannot change its calling. Connect the number again.
whatsapp_number_taken	409	This number is already connected to another workspace.
whatsapp_token_not_granted	422
whatsapp_webhooks_not_subscribed	502	Meta did not confirm the webhook subscription. Try again.
whatsapp_window_closed	422	WhatsApp only allows free-form messages within 24 hours of the customer’s last message.

Webhooks

Code	Status	Meaning
webhook_endpoint_disabled	409	The endpoint is turned off.
webhook_endpoint_limit	409	A partner can have … webhook endpoints. Delete one it no longer uses first.

Realtime

Code	Status	Meaning
upgrade_required	426	Open this endpoint as a WebSocket, version 13.

Workspace

Code	Status	Meaning
approver_is_proposer	403	You proposed this change, so another admin must approve it.
domain_taken	varies
email_not_verified	403	Verify your email address before accepting an invitation.
embed_origin_limit	409	A workspace can have at most 20 embed origins. Remove one first.
file_infected	403	This file was flagged as malware and can’t be opened.
file_not_scanned	409	This file has not been scanned for malware. Confirm that you want to open it anyway.
impersonation_approval_expired	409	The approval expired … minutes after it was given. Request the session again.
impersonation_not_allowed	403	Exports and call credentials are not available while viewing a workspace.
impersonation_read_only	403	You are viewing this workspace read-only. Nothing can be changed.
invitation_email_mismatch	403	This invitation was sent to a different email address. Sign in with that address to accept it.
invitation_expired	410	This invitation has expired. Ask for a new one.
last_team	409	You can’t delete the only team. Routing needs at least one.
role_escalation	403	Only an owner can make, change or remove an owner.
routing_draft_stale	409	Routing was published after this draft was started. Review the draft and save it again, then publish.
routing_ivr_draft_only	409	The call menu changes only through the routing draft: save it to /routing/draft, then publish it with /routing/draft/publish.
slug_taken	409	This workspace address is already taken.
team_name_taken	409	A team called … already exists.
upload_incomplete	409	The file has not been uploaded yet. Upload it with the form, then confirm.
upload_mismatch	422	The uploaded file does not match what was announced or is not the type it claims to be. Upload it again.
workspace_limit_reached	409	You already own … workspaces, the most allowed. Contact support to add another.
workspace_read_only	403	This workspace is cancelled. You can view it but not change anything.