Platform
Errors
Every error is JSON with a stable machine-readable code beside a human-readable message. Branch on the code, never on the message.
{
"statusCode": 403,
"code": "API_KEY_SCOPE_MISSING",
"error": "Forbidden",
"message": "This API key does not have the 'contacts:read' scope",
"requiredScope": "contacts:read",
"requestId": "3b1f…",
"docUrl": "https://trovacast.com/developers/errors#code-api-key-scope-missing",
"timestamp": "2026-10-05T10:00:00.000Z",
"path": "/v1/contacts"
}codeis stable: branch on it.messageis for people and may change; a validation failure lists each problem in it.requestIdidentifies the request (also theX-Request-Idheader). Quote it to support.docUrllinks to the code's row in Every error code below — what it means and what to do. The link is stable: keep it in a log line or a ticket. The SDKs expose it aserror.docUrl(Node.js),error.doc_url(Python) andapiErr.DocURL(Go).- Some errors carry more fields:
requiredScopeon a missing scope, areasonon an invalid webhook URL.
Handling an error
| Status | What to do |
|---|---|
400, 422 | Fix the request. Retrying the same request returns the same answer. |
401 | The key is missing, wrong, revoked or expired, or its project is not active. Check the key you deployed. |
403 | The key lacks a scope (requiredScope says which) or is the wrong kind for the endpoint. |
404 | Not found for this key: it does not exist, or it belongs to another project. |
409 | The resource's state does not allow this, or a uniqueness clash. Read the resource, then decide. |
402 | Billing refused the action — usually not enough prepaid credit. A BILLING_* code says why. |
429 | Too many requests. Wait Retry-After seconds, then retry. |
5xx | Retry with backoff — with the same Idempotency-Key on a write — until an answer carries Idempotent-Replayed: true. See Idempotency. |
Every error code
Rendered from the API's error-code registry: what each code means and what to do about it. Each endpoint's reference also lists the statuses it can answer with.
| Code | Status | Meaning and what to do |
|---|---|---|
AGENT_BUSY | 409 | The agent the call was to be offered to (a BRIDGE call to a seat, or a flow’s connect to one) is on another call.What to do: Offer the call to another agent, or to a queue, or try this agent again once they are free. |
AGENT_OFFER_UNAVAILABLE | 503 | The desk could not offer the call to an agent right now. Nothing was connected.What to do: Retry shortly with backoff. POST /v1/calls runs again under the same Idempotency-Key; a call action or a conference write stores this error against its key, so retry those with a new one. |
AGENT_PHONE_REQUIRED | 422 | A BRIDGE call with ringFirst: agent names a seat with no phone on file to ring first.What to do: An administrator adds the agent’s phone to their team membership in the console, or ring the contact first (ringFirst: contact). |
AGENT_STREAM_URL_INVALID | 422 | agent.streamUrl is not a public wss:// URL (credentials in it, a private host or address); reason says which. Checked again every time the socket connects. See Calls.What to do: Use a wss:// URL on a public host that resolves to public addresses, with no credentials in it — put your secret in agent.token, which arrives as Authorization: Bearer. |
AGENT_TOOL_SECRET_REQUIRED | 422 | The call (aiAgent on POST /v1/calls) or the number’s ai route (route.ai on PATCH /v1/numbers/{numberId}) gives the agent tools or a session webhook. Both are signed with the agent’s tool-signing secret so your endpoint can tell them from a forgery, and this agent has none. Nothing was dialled or changed.What to do: Create the agent’s secret with POST /v1/agents/{agentId}/tool-secret (it is shown once; keep it where your endpoint verifies Trovacast-Signature), then retry. |
AI_AGENT_INACTIVE | 409 | aiAgent.agentId — or (2026-11-07) a new ai route on PATCH /v1/numbers/{numberId} — names an AI agent that is switched off (active: false) or archived. Nothing was dialled, and the route was not changed. See AI voice agents.What to do: Switch a switched-off agent on with PATCH /v1/agents/{agentId} (active: true); for an archived one, name another agent. |
AI_AGENT_IN_USE | 409 | A number routes its inbound calls to this AI agent, so it cannot be archived. See AI over the API.What to do: Route the number elsewhere first (PATCH /v1/numbers/{numberId}), then archive the agent again. |
AI_AGENT_NAME_TAKEN | 409 | Another AI agent of the organization already has that name.What to do: Choose another name, or change the existing agent instead (PATCH /v1/agents/{agentId}). |
AI_AGENT_NOT_FOUND | 404 | aiAgent.agentId — or (2026-11-07) a new ai route on PATCH /v1/numbers/{numberId} — names no AI agent of this organization of the request's mode (GET /v1/agents lists them; a test agent on a live call or number reads exactly as an unknown one). Nothing was dialled, and the route was not changed.What to do: Pass an agentId from GET /v1/agents, using a key of the same mode as the agent (a number takes live calls: route it to a live agent). |
AI_AGENT_VERSION_CONFLICT | 409 | The AI agent changed since the version you sent (the body carries the current version). See AI voice agents.What to do: Read it again with GET /v1/agents/{agentId} and, if your change still applies, retry with the current version. |
AI_CALLS_DISABLED | 409 | The organization's call policy turns machine-run calls off.What to do: Turn AI calls on with PATCH /v1/settings/calls (aiCallsEnabled: true and the version from GET /v1/settings/calls; a live key with settings:write), or in the console under Settings → Calling policy, then retry. See Turn AI calls on or off. |
AI_PROVIDER_UNAVAILABLE | 422 | mode: AI_AGENT named an AI agent whose voice cannot run on this deployment — or (2026-11-07) a transfer action named a call flow that hands callers to such an agent (agentId names it; nothing was changed on the call): reason is voice_key_missing (its provider has no key here), agent_id_missing (an ElevenLabs voice with no ElevenLabs agent id), transcription_key_missing or reasoning_key_missing (a composite voice without its speech-to-text or reasoning key); provider and leg name the leg. Nothing was written or dialled — no call, no call.* event. The same code is a call’s failure.code when its voice could not start once the call existed. See AI voice agents.What to do: Do not retry the same request: it is refused the same until the agent or the deployment changes. Check GET /v1/agents/{agentId} (availability), then choose an agent that reads runnable: true, or switch this one to a voice GET /v1/models marks available. On a test key, build the agent on the mock voice. |
ANSWER_URL_INVALID | 422 | flow.answerUrl is not an https URL on the voice application’s own origin (the answer or fallback URL’s), or not one Trovacast will call (a private host, a service port). Nothing was dialled. See Inbound calls.What to do: Use an https URL on the application’s own origin, on a public host and an allowed port — or leave flow.answerUrl out to ask the application’s answer URL. |
API_KEY_INVALID | 401 | The key is missing, malformed, unknown, revoked or expired, or its project or integration is not active. The same answer for every case, so it never reveals whether a key existed. See Authentication.What to do: Send the whole key as Authorization: Bearer tc_live_… (or tc_test_…). A revoked or expired key never works again: create a new one in Settings → Developers; a suspended project's keys work again once it is reactivated. |
API_KEY_KIND_MISMATCH | 403 | A project key on an integration endpoint, or an integration key on a project endpoint.What to do: Call /v1/organizations with an integration key and every other endpoint with a project key. See Integration keys. |
API_KEY_SCOPE_MISSING | 403 | The key lacks the scope the endpoint (or a webhook event) requires; requiredScope names it. See Scopes.What to do: Use a key that holds requiredScope: a project administrator creates one in Settings → Developers (an existing key's scopes can be narrowed, never widened). Retrying with this key cannot succeed. |
APPLICATION_NOT_FOUND | 404 | flow.applicationId (or a transfer’s to.applicationId) names no voice application of this organization.What to do: Pass an id from GET /v1/applications, using a key of the same mode as the application. |
ASSIGNEE_NOT_A_MEMBER | 422 | The userId or email given to assign a conversation is not an active member of the project — the same answer for an unknown user, a removed member or another project’s user.What to do: Check the userId or email, or add the person to the project in Settings → Members first. |
AUDIENCE_EMPTY | 409 | Nobody in the broadcast’s audience can be sent to — or nobody matches it. audience carries the counts by reason (no consent, no number, opted out, …), so you can see who was left out. Nothing was created.What to do: Act on the counts — record the missing consent, fill in missing variables, or widen the audience — then create the broadcast again. |
AUDIENCE_TOO_LARGE | 422 | The audience matches more contacts than one broadcast may reach; matched and limit are in the body.What to do: Narrow the audience to at most limit contacts, or split it into several broadcasts. |
AUDIO_UNAVAILABLE | 422 | The audio for play, a gather prompt or hold music could not be fetched, or is not a playable WAV (16-bit PCM or µ-law, mono or stereo, 8–48 kHz, at most 5 MB); reason says which. Nothing was played.What to do: Host a WAV that fits those limits at a public https URL that answers within 8 seconds, then send the action again. See Limits. |
BAD_GATEWAY | 502/504 | An upstream provider (Meta, for example) failed or timed out.What to do: Retry with exponential backoff and the same Idempotency-Key. An answer with Idempotent-Replayed: true is final for that key: read the resource to see whether the first attempt took effect before sending it again with a new key. |
BILLING_INSUFFICIENT_CREDIT | 402 | The prepaid wallet, after any included plan minutes, cannot cover the messages at your plan's rate — or a call's ceiling: its maxDurationSec in started minutes, beside what your live API calls already in flight can still run to (inFlightMinutes), each at its own rate.What to do: Top up the prepaid balance (POST /v1/balance/top-ups, or Add credit in Settings → Billing), then retry. When the refusal carries maxDurationSecAvailable, a call with a maxDurationSec up to it is placed now; without it no shorter call fits — retry once a call in progress ends. See Limits and billing. |
BILLING_PAID_BY_INTEGRATION | 409 | A top-up for an organization whose charges its integration pays: its own wallet is not spent, so credit goes to the integration's billing organization instead.What to do: Top up the integration's billing organization (with its own key, or in its console). Retrying will not help. |
BILLING_PAYER_NOT_CONFIGURED | 409 | billing.payer: integration was asked before the platform named your integration's billing organization — the account whose wallet pays for your organizations.What to do: Contact us to set it, then retry; until then provision with billing.payer: organization (each organization pays from its own wallet). |
BILLING_PAYMENTS_UNAVAILABLE | 409 | Online payments are not configured on this deployment, so no checkout can be started.What to do: Retrying will not help: contact us to add credit another way. |
BILLING_RATE_UNAVAILABLE | 503 | Your plan has no rate for this channel and mode (or message category) — a configuration gap on our side, not a debt.What to do: Retrying will not help until the plan prices it: contact us. GET /v1/pricing shows the rates your plan has. |
BILLING_SPEND_CAP_REACHED | 402 | The organization's charges are paid by its integration, and the monthly cap the integration set (spendCapMinor) would be passed: spentThisPeriodMinor of it is already spent this UTC month.What to do: Retrying will not help this month unless the integration raises the cap (PATCH /v1/organizations/{organizationId} with billing.spendCap); a call or send the plan's allowance covers, or a free one, still goes. The cap resets on the 1st (UTC). |
BILLING_SUBSCRIPTION_CANCELED | 402 | The subscription was cancelled at a period end.What to do: A project administrator chooses a plan in Settings → Billing, which reactivates the subscription; then retry. |
BILLING_SUBSCRIPTION_PAST_DUE | 402 | The monthly fee is unpaid: it left the wallet negative.What to do: Top up enough to bring the balance back to zero or above (POST /v1/balance/top-ups): the subscription reactivates by itself, then retry. |
BILLING_SUBSCRIPTION_SUSPENDED | 402 | The subscription is blocked by the platform.What to do: Retrying will not help until the hold is lifted: contact us. |
BILLING_TOP_UP_ABOVE_MAXIMUM | 400 | The top-up is above the online limit (maximumTopUpMinor).What to do: Ask for at most maximumTopUpMinor in one top-up — split a larger amount into several — or contact us for a larger transfer. |
BILLING_TOP_UP_BELOW_MINIMUM | 400 | The top-up is below your plan’s minimum (minimumTopUpMinor). See Top-ups.What to do: Retry with an amountMinor of at least minimumTopUpMinor, which the answer carries. |
BRIDGE_AGENT_NOT_FOUND | 404 | bridge.to.agentMembershipId names no active seat of this organization. Nothing was dialled.What to do: Pass the membership id of an active seat of this organization, or bridge to an outside number (bridge.to.number). |
BROADCAST_INVALID_STATE | 409 | The broadcast’s status does not allow this — pausing a completed broadcast, resuming one that is not paused, cancelling one already finished.What to do: Read the broadcast again (GET /v1/broadcasts/{broadcastId}) and act on its current status; a finished broadcast takes no further action. |
CALLER_ID_NOT_OWNED | 422 | from is not a voice-capable number the organization owns on the call's channel. When the carrier cannot answer for its inventory right now the call is a 503 instead.What to do: Set from to one of your assigned voice numbers on the call's channel (GET /v1/numbers), or leave it out to use the channel's own caller ID. Retry the 503 with backoff. |
CALLER_ID_UNSUPPORTED | 422 | from was sent on a channel that cannot check a chosen caller ID (callerIdSelection: false in GET /v1/calls/channels); provider names the channel.What to do: Leave from out to use the channel's own caller ID, or set provider to a channel with callerIdSelection: true. |
CALLER_NUMBER_INACTIVE | 422 | The caller ID is one of the organization's numbers, but it is suspended (for example for unpaid rental) or being released.What to do: Call from another of your assigned numbers (GET /v1/numbers), or top up the balance: a number suspended for unpaid rental comes back by itself shortly after a top-up covers its rental. |
CALLING_WINDOW_CLOSED | 409 | respectCallingWindow is on and it is outside the calling window (09:00–21:00 in the organization's time zone, unless the deployment sets another). The body carries nextAllowedAt, timeZone and window.What to do: Place the call again at or after nextAllowedAt. |
CALL_ACTION_IN_PROGRESS | 409 | Another prompt or gather (or a call flow) is still speaking on the call; runningActionId or reason says which. A transfer does not wait: it pre-empts the prompt.What to do: Wait for it to finish — a gather ends with call.gather.completed, a transfer with call.transferred — then act again. |
CALL_ACTION_UNSUPPORTED | 409 or 422 | The action, or one of its options, is not available on this call or this deployment (reason): for example a speech gather where the deployment has no speech recognition, a stored audio asset, a leg the call does not have, a mode the deployment does not offer, or connecting a live call to an AI agent. See Call control.What to do: Change the request as reason says — gather dtmf, play a WAV URL, act on the root call (rootCallId) rather than a leg — since retrying it unchanged fails the same way. |
CALL_CONCURRENCY_LIMIT | 429 | Over the organization's or the key's cap on live API calls (scope is organization or key, with limit and liveCalls) — or, with livemode: false and testCalls in place of liveCalls, over the sandbox's own cap on test calls. Each mode counts only its own calls.What to do: Place the call again once one of your calls in the same mode ends (watch call.completed), backing off between attempts. See Limits and billing. |
CALL_FLOW_INVALID | 422 | The call-flow document does not validate; issues lists each problem with its path. See Call flows.What to do: Fix each problem in issues at its path and send the document again; check drafts first with POST /v1/call-flows/validate. |
CALL_FLOW_NOT_FOUND | 404 | flow.callFlowId (or a transfer’s to.callFlowId) names no call flow of this organization, or an archived one.What to do: Pass the id of a call flow that is not archived (GET /v1/call-flows), using a key of the same mode as the flow. |
CALL_FLOW_NOT_PUBLISHED | 409 | The call flow has no published version to run.What to do: Publish a version with POST /v1/call-flows/{callFlowId}/versions/{versionId}/publish, then retry. |
CALL_NOT_AFTER_PASSED | 422 | POST /v1/calls named a notAfter that has already passed: nothing is dialled at or after it, and nothing was created. (A call accepted in time that could not be handed to the carrier before it ends failed with failure.code: NOT_AFTER_PASSED instead.)What to do: Send a later notAfter, or none — or leave the call: it was meant not to happen after that time. |
CALL_NOT_ANSWERED | 409 | The call is not answered yet: actions start once it is in_progress (after call.answered).What to do: Act again once call.answered has arrived. |
CALL_NOT_CONTROLLABLE | 409 | The call’s audio does not stream through Trovacast (a phone-leg or SIM call), so it cannot be spoken to, held or transferred from the API.What to do: Do not retry. Only calls whose audio streams through Trovacast can be controlled — every POST /v1/calls mode, and inbound calls routed to a flow or an application. |
CALL_NOT_HELD | 409 | resume on a call that is not on hold.What to do: Nothing to resume: send resume only after a hold (call.held). |
CALL_NOT_LIVE | 409 | The call has ended, or never went live. Nothing was done.What to do: Do not retry: read the call (GET /v1/calls/{callId}) for how it ended. |
CALL_ON_ANOTHER_REPLICA | 409 | The Trovacast server carrying the call’s audio could not be reached in time (it is restarting or failed). Any other server forwards actions to it, so this is rare.What to do: Retry shortly with the same Idempotency-Key, which is safe: the action runs at most once. |
CARRIER_RATE_LIMITED | 429 | The carrier is throttling dials and nothing rang. The body names the call (callId) and retryAfterSeconds, also sent as Retry-After.What to do: Wait retryAfterSeconds, then retry under the same Idempotency-Key: the retry dials afresh. |
CARRIER_REJECTED | 502 | The carrier refused the dial and nothing rang. The call exists as failed (callId).What to do: Retry with backoff under the same Idempotency-Key, which dials afresh. If the carrier keeps refusing, read the call's failure (GET /v1/calls/{callId}) and check the number. |
CHANNEL_NOT_CONFIGURED | 409 | The project has not set the channel up — email: no email account of its own (the platform’s mail never sends for it); SMS: no SMS settings or DLT entity id — or the deployment does not carry it. On a call, the provider is not a channel this deployment runs or the organization has set up. Also a message.failed code when the account was disconnected after the message was queued; nothing was sent.What to do: Set the channel up in Settings → Channels (WhatsApp, Email or SMS) — for a call in Settings → Calling, or leave provider out — then retry. A message that failed with this code was never sent: send it again once the account is connected. |
CHANNEL_UNSUPPORTED | 422 | The channel cannot carry this kind of call: it does not stream the call's media to your agent (externalAgent: false in GET /v1/calls/channels) or into a flow or bridge (flows: false), or it cannot ring an agent first (agentFirst: false); provider names it.What to do: Set provider to a channel whose GET /v1/calls/channels entry has what the call needs; for an agent-first bridge, ring the contact first instead. |
CHILD_DIAL_DESTINATION_NOT_ALLOWED | 422 | The number a BRIDGE call or a transfer would dial is outside the organization’s list of destinations for connected parties (India by default). Nothing was dialled.What to do: Dial a number inside that list, or contact us to widen it for your organization. |
CHILD_LEG_LIMIT | 409 | The call already has as many live legs dialled from it as it may (transfer targets, bridged numbers).What to do: End one of its legs first (POST /v1/calls/{callId}/hangup on the leg), then add the party again. |
CHILD_LEG_UNSUPPORTED | 503 | The call’s channel cannot stream a leg dialled from a live call, so it cannot bridge or transfer to a number on this deployment.What to do: Retrying will not help on this channel: transfer to a queue, a call flow or a voice application instead, which dials no leg. |
CONFERENCE_ENDED | 409 | The conference's call has ended: nobody can be added, muted or removed. POST /v1/conferences/{conferenceId}/end still answers it as it stands.What to do: Do not retry on this conference: it is over. GET /v1/conferences/{conferenceId} shows who took part. |
CONFERENCE_NOT_FOUND | 404 | No conference with that id in this organization. A conference's id is its call's; a call never opened as one (POST /v1/conferences) is not a conference. See Conferences.What to do: Open the call as a conference first (POST /v1/conferences with its callId), or check the id. |
CONFERENCE_PARTICIPANT_NOT_FOUND | 404 | No such party in the conference (a party's id is its leg's, from participants), or — when adding an agent — no active seat with that id in the organization.What to do: Use a party’s id from participants (GET /v1/conferences/{conferenceId}), or the membership id of an active seat when adding an agent. |
CONFERENCE_PARTICIPANT_UNSUPPORTED | 422 | Not available on a conference (reason): call — moving another live call in is not supported yet; caller — the caller is the conference call itself; leg — a leg dialled from another call cannot be opened as a conference.What to do: Act on reason: for call, dial its party’s number in instead (to.number); for caller, end the conference to hang them up; for leg, open its root call (rootCallId). |
CONFLICT | 409 | The resource's state does not allow this, there is a uniqueness clash, or it changed concurrently.What to do: Read the resource again, then decide: retry against its current state (with its new version where it has one), or choose another value for a uniqueness clash. |
CONSENT_MARKETING_REQUIRED | 409 | A marketing message to a contact who agreed to updates (transactional or utility messages) only: it needs marketing: opted_in on the channel. See Consent.What to do: Send a non-marketing message instead — a utility template, a transactional email, a service SMS — or record the contact's marketing opt-in once they give it (PUT /v1/contacts/{contactId}/consent/{channel}). |
CONSENT_OPTED_OUT | 409 | The contact opted out on this channel — or, for a marketing message, out of marketing — whether you recorded it or they did (STOP, an unsubscribe, a spam report).What to do: Do not retry. After a marketing opt-out a transactional or utility message may still go; only a new opt-in reopens the channel — theirs, if they opted out themselves. See What a send needs. |
CONSENT_REQUIRED | 409 | No opt-in on file for this kind of message on this channel.What to do: Record the contact's consent with PUT /v1/contacts/{contactId}/consent/{channel} once you have collected it (a WhatsApp or email refusal carries the contactId), then send again. See Record a decision. |
CONSENT_SELF_OPT_OUT | 409 | A consent write refused: it would override an opt-out the contact made themselves. An opted_out is never refused.What to do: Do not retry: only the contact can reopen it (on WhatsApp, a typed START restores updates). See The contact’s own opt-outs. |
CONTACT_BLOCKED | 409 | The contact is blocked, so nothing is sent to them.What to do: Do not retry: nothing reaches a blocked contact, on any channel. |
CONTACT_CALL_IN_PROGRESS | 409 | The contact is on a live call, so they cannot be erased yet.What to do: Retry the erasure once the call has ended (call.completed), with the same Idempotency-Key. |
CONTACT_DO_NOT_CALL | 409 | The contact is on the do-not-call list; no call is placed.What to do: Do not retry or dial the number another way. If the contact asks to be called again, a project member changes their state in the console. |
CONTACT_EVENT_IN_PROGRESS | 409 | A message or status about the contact is being applied right now, so the contact was not erased (nothing was touched).What to do: Retry shortly — usually seconds — with the same Idempotency-Key. |
CONTACT_NOT_FOUND | 404 | The contactId a request named is not a contact of this organization, or was erased. Like every 404, another organization's id reads the same.What to do: Check the id (GET /v1/contacts?phone= finds a contact by number), or send by to.phone or to.email to use or create the contact; an erased contact never comes back. |
CONTACT_OPTED_OUT | 409 | On a send, the contact opted out of all contact or asked not to be contacted — it outranks every channel's consent. On a call, they opted out of calls themselves.What to do: Do not retry, and do not reach them another way. If the contact asks to hear from you again, a project member changes their state in the console. |
CONTACT_PHONE_REQUIRED | 422 | The contact has no phone number — they are known by their WhatsApp user id alone — so they cannot be called.What to do: Do not retry: reach them on WhatsApp instead. If WhatsApp later shares their number, it lands on the contact by itself. See Contacts without a phone number. |
CONVERSATION_CHANGED | 409 | The conversation moved on since you read it (a new message, another assignment or status change), or the version you sent is not its current one. See Conversations.What to do: Read the conversation again (GET /v1/conversations/{conversationId}) and, if the action still makes sense, retry with its current version. |
CONVERSATION_NOT_FOUND | 404 | The conversationId of a send, or of a conversation read, names no conversation this key can see — another project’s, or one of the other mode: a test thread (the sandbox’s, or a test contact’s) to a live key, a live customer’s to a test key.What to do: Check the id against GET /v1/conversations (or the conversationId of the customer’s message.received) with a key of the same mode, or send by contactId instead. |
DESTINATION_ACKNOWLEDGEMENT_REQUIRED | 422 | +1 is opened for your organization, but it has not acknowledged the TCPA statement yet (or the statement changed since). GET /v1/settings/destinations shows tcpa.acknowledged.What to do: Acknowledge the statement — with your key (POST /v1/settings/destinations/tcpa with its currentStatementVersion) or in the console, under the calling policy’s Destinations — then retry. |
DESTINATION_BLOCKED | 422 | The number is in a country code your organization may not call: a call to a contact reaches the home market (+91, defaultCountryCodes) and the countries the platform opened for you (openedCountryCodes) only, and +1 (North America) is blocked on every path, transfers included. The platform can open a country for your organization (priced on your plan with a rate of its own); GET /v1/settings/destinations says what applies (countryCallingCode names the code, absent when the number's country could not be read).What to do: Retrying will not help: call a number you may reach, or contact us to open the country for your organization. See Destinations. |
DESTINATION_CALLING_WINDOW_CLOSED | 409 | A +1 call outside 08:00–21:00 (or a narrower window this deployment sets) in the called party’s local time — the zone the request states (calledPartyTimeZone), else every zone the number’s area code serves — on every path, respectCallingWindow: false included. nextAllowedAt says when it opens.What to do: Place the call again at or after nextAllowedAt; no request option lifts this window. If you know the called party’s time zone, state it in calledPartyTimeZone. |
DESTINATION_NOT_PRICED | 422 | The destination lies beyond the default your calls reach (a country code opened for you, or a leg to a widened prefix) and your plan has no rate of its own for it — the home market’s rate never prices a call abroad. GET /v1/pricing shows your rates.What to do: Retrying will not help until the destination is priced: contact us to have it added to your plan. |
DESTINATION_STATEMENT_OUTDATED | 409 | The TCPA statement you acknowledged (POST /v1/settings/destinations/tcpa) is not the current one: it changed since you read it. An acknowledgement is of the exact words. currentStatementVersion is in the body.What to do: Read the statement again (GET /v1/settings/destinations: tcpa.statement, tcpa.currentStatementVersion), have it accepted, and acknowledge that version. |
DIAL_ADMISSION_UNAVAILABLE | 503 | A pre-dial compliance check could not run (a dependency did not answer), so the call was not placed. Nothing was dialled or billed.What to do: Retry with backoff and the same Idempotency-Key. If it persists, contact us with the requestId. |
DLT_ALREADY_REGISTERED | 409 | The DLT entity (its PE id) or header is recorded for this project already — by POST /v1/dlt/entities, POST /v1/dlt/headers, or a PATCH that changes an entity’s PE id to one recorded already.What to do: Use the existing record: GET /v1/dlt/entities lists every entity with its headers, their id and status. To correct a pending or rejected entity, send PATCH /v1/dlt/entities/{entityId} rather than submitting it again. |
DLT_HEADER_REQUIRED | 422 | The 140-series number has no verified DLT voice header of this organization — on a call from it, or on activating it.What to do: Register a voice header for this exact number under Settings → DLT registrations and wait for it to be verified, then retry; until then the same request fails the same way. |
DLT_NUMBER_NOT_HELD | 422 | A voice_140 or voice_160 header named a number that is not one of this project’s own numbers of that series (held or assigned). A voice header registers your number on DLT; it never reserves someone else’s.What to do: Hold or rent the 140- or 160-series number first (POST /v1/numbers; GET /v1/numbers lists yours, with their type), then record its header. A 140-series number stays on hold until its header is verified, then activates. A number you released, or a hold that lapsed, no longer counts. |
DLT_REGISTRATION_CLAIMED | 409 | Another project holds that DLT header: a header is registered to one principal entity across the platform while it is pending, verified or suspended (a rejected one holds nothing). The answer never says whose. When theirs is still pending, your claim waits in the platform’s review queue beside it.What to do: Retrying cannot succeed. The platform reviews a claim on a pending header and either awards it to you (your header appears, pending, and dlt.header.updated tells you) or leaves it with its holder. If the header is registered to your business on DLT and is verified elsewhere, contact us with the portal’s record of it: the platform can release it. |
DLT_REGISTRATION_CONTESTED | 409 | Another business claims this header’s value and the platform has not decided, so the header — and the entity it is under — cannot be withdrawn: withdrawing and recording it again would wipe the claim. Only the platform decides a contested value.What to do: Retrying cannot succeed until the platform decides. If the value is yours on DLT, contact us with your DLT registration; the platform keeps the value with you (the claim is dismissed) or awards it to the claimant. |
DLT_REGISTRATION_LOCKED | 409 | The platform’s record of what DLT holds is not changed from here: a verified or suspended header, and a verified, suspended or rejected entity, cannot be deleted or edited. See SMS.What to do: Retrying unchanged cannot succeed. To correct a verified, suspended or rejected entity, contact us to have the platform reopen it: once it is pending again, it can be edited. To withdraw a verified registration, have the platform suspend it. A different PE id or header is submitted as a new registration. |
DLT_REGISTRATION_REJECTED | 409 | The platform rejected this header value for your project — it rejected your header, or awarded the value to another business’s claim — so your project cannot record it again.What to do: Retrying cannot succeed. Record a header of your own. If the rejection was a mistake, contact us with your DLT registration: the platform can lift it, and you can then record the value as a fresh claim (the platform reviews it beside any holder). |
DLT_VERSION_CONFLICT | 409 | The DLT registration changed since the version you sent: the platform reviewed it, or another request changed it.What to do: Read it again (GET /v1/dlt/entities/{entityId} or GET /v1/dlt/headers/{headerId}), check the change still makes sense, and retry with its current version. |
DTMF_INVALID | 422 | digits uses keys other than 0-9 * # and w (a half-second pause), or more than 32.What to do: Send at most 32 keys from 0-9, *, # and w. |
EMAIL_DOMAINS_UNAVAILABLE | 503 | Amazon SES is not available on this deployment, so sending domains cannot be managed.What to do: Retrying will not help: send through your own SMTP account (Settings → Channels → Email) instead, or contact us. |
EMAIL_DOMAIN_ALREADY_ADDED | 409 | This project has already claimed the domain.What to do: Use the domain you have (GET /v1/email/domains/{domain}): publish its records and re-check it instead of adding it again. |
EMAIL_DOMAIN_CLAIMED | 409 | Another project holds the domain. The body carries a challenge TXT record.What to do: Publish the challenge TXT record and claim the domain again (POST /v1/email/domains): a holder that has not verified it gives way at once, and a never-verified claim lapses 72 hours after it was first made. A verified holder never gives way — contact us. |
EMAIL_DOMAIN_LIMIT | 409 | The project already holds the most sending domains it may (limit: 10 by default, or the project's own cap the platform set).What to do: Delete a domain you no longer send from (DELETE /v1/email/domains/{domain}), then add the new one — or ask us to raise the project's cap. |
EMAIL_DOMAIN_NOT_VERIFIED | 409 | The project sends through Amazon SES and its sending domain is not verified (or was removed, or stopped verifying).What to do: Publish the DNS records GET /v1/email/domains/{domain} lists, re-check with POST /v1/email/domains/{domain}/verify, and send once its status is verified. |
EMAIL_DOMAIN_OVERLAP | 409 | Another project holds a parent domain or a subdomain of it. Like EMAIL_DOMAIN_CLAIMED, it carries a challenge.What to do: Publish the challenge TXT record and claim again: unverified claims give way at once. A verified holder never does — contact us. |
EMAIL_DOMAIN_PENDING_LIMIT | 409 | The project already has 3 sending domains that are not yet verified.What to do: Verify one of them (publish its records, then POST /v1/email/domains/{domain}/verify) or delete one you do not need, then add the new one. |
EMAIL_DOMAIN_RELEASING | 409 | The domain’s previous identity is still being deleted.What to do: Retry the claim in a few minutes. |
EMAIL_DOMAIN_UNAVAILABLE | 409 | An identity for the domain exists in the sending account outside any project.What to do: Retrying will not help: contact us to have it cleared. |
EMAIL_SENDING_SUSPENDED | 409 | The project’s email is suspended: its hard-bounce or complaint rate on the shared sending account crossed the threshold.What to do: Retrying will not help until support reviews and lifts it: contact us, and stop mailing the addresses that bounce or complain. |
EMAIL_SUPPRESSED | 409 | The address — the recipient’s or a copy’s — is on the project’s suppression list; reason is hard_bounce, soft_bounce, complaint or manual. See Email.What to do: Do not send to that address — drop a suppressed copy from cc or bcc. Remove the entry (DELETE /v1/email/suppressions/{suppressionId}) only once you know the address takes your mail again; a soft_bounce lapses by itself after 7 days. |
ENTITLEMENT_CALLING_DISABLED | 403 | Calling is not enabled for this project (it is messaging-only). GET /v1/me shows the project's entitlements.What to do: A project cannot turn calling on itself: the platform, or the partner that manages the project, enables it. Contact us; retrying will not help until then. |
ENTITLEMENT_MESSAGING_DISABLED | 403 | Messaging is not enabled for this project (it is calling-only). GET /v1/me shows the project's entitlements.What to do: A project cannot turn messaging on itself: the platform, or the partner that manages the project, enables it. Contact us; retrying will not help until then. |
ERASURE_STORAGE_UNAVAILABLE | 503 | Stored media or a call recording could not be deleted. The erasure stopped before any record was touched; nothing was lost.What to do: Retry with backoff and the same Idempotency-Key: an erasure runs again. If it persists, contact us with the requestId. |
FLOW_ARCHIVED | 409 | The call flow is archived: it takes no new version and cannot be published.What to do: Do not retry: create a new call flow (POST /v1/call-flows) with the document instead. |
FLOW_INVALID | 422 | The call-flow service refused the document on save or publish (the backstop of CALL_FLOW_INVALID), for example a target that no longer exists.What to do: Validate the document again (POST /v1/call-flows/validate), fix what it names, then save or publish again. |
FLOW_IN_USE | 409 | Numbers still route to the call flow, so it cannot be archived.What to do: Route those numbers elsewhere first (PATCH /v1/numbers/{numberId}), then archive it again. |
FLOW_NAME_TAKEN | 409 | Another call flow of the organization already has that name.What to do: Choose another name, or change the existing flow instead (PATCH /v1/call-flows/{callFlowId}). |
FLOW_VERSION_CONFLICT | 409 | The call flow changed since the version you sent.What to do: Read it again (GET /v1/call-flows/{callFlowId}) and retry with its new version. |
FORBIDDEN | 403 | Refused for another reason than a missing scope.What to do: Read message for the reason: the same request with this key will not succeed. If it is unclear, contact us with the requestId. |
FROM_NOT_ALLOWED | 409 | email.from or senderId is not one of the project’s senders: not under a verified sending domain, nor the SMTP account’s own address.What to do: Send from an address under one of your verified sending domains (GET /v1/email/domains), or from the SMTP account’s own address. |
HANGUP_FAILED | 503 | The carrier (or the server carrying the call's stream) did not confirm the hang-up, so the line may still be up.What to do: Retry POST /v1/calls/{callId}/hangup — with the same Idempotency-Key if you sent one: the endpoint runs again rather than replaying the error. A hangup call action stores this error against its key, so retry that with a new key. |
HANGUP_NOT_READY | 409 | The call can be ended, but not yet: the carrier has not answered the dial with the id it is ended by, or — on a channel without remoteHangup — the contact has not answered.What to do: Retry after retryAfterSeconds (also Retry-After); once the call can be ended, the retry ends it. |
HANGUP_UNSUPPORTED | 409 | The call's channel can never end it remotely: it has no remote hang-up and no stream the platform holds or awaits to close.What to do: Do not retry: this call ends only when a party on it hangs up. |
IDEMPOTENCY_KEY_INVALID | 400 | The Idempotency-Key header is not 1–255 visible ASCII characters.What to do: Send a key of 1–255 visible ASCII characters — a UUID, or an id from your own system — or leave the header out. See Idempotency. |
IDEMPOTENCY_KEY_IN_FLIGHT | 409 | The first request with this key is still running.What to do: Wait Retry-After seconds, then send the same request with the same key; it never runs twice. See Idempotency. |
IDEMPOTENCY_KEY_REUSED | 422 | The key was already used for a different request (another body or path).What to do: Use a new key for a new request. To retry the first one, send exactly its body and path with this key. |
INTERNAL_ERROR | 500 | Our fault: the request failed on the platform's side.What to do: Retry with backoff and the same Idempotency-Key; an answer with Idempotent-Replayed: true is final, so read the resource before sending it again with a new key. If it persists, contact us with the requestId. |
LIVE_KEYS_REQUIRE_VERIFICATION | 403 | The organization signed up on its own and its business verification is not approved yet, so only test-mode keys (tc_test_…) work. See Authentication.What to do: Use a test key until the verification is approved: fill it in and submit it under Settings → Business verification, or over the API with a test key. See Business verification. |
MACHINE_DETECTION_UNSUPPORTED | 422 | machineDetection was sent on a channel that cannot tell an answering machine from a person (machineDetection: false in GET /v1/calls/channels); provider names the channel. See Calls.What to do: Leave machineDetection out, or set provider to a channel with machineDetection: true. |
MEDIA_CAPACITY | 503 | The server carries as many streamed calls as it may right now. Nothing was dialled or connected.What to do: Retry shortly with backoff. POST /v1/calls runs again under the same Idempotency-Key; a call action or a conference write stores this error against its key, so retry those with a new one. |
MEDIA_CONTENT_MISMATCH | 422 | The file’s bytes are not the type the link claims.What to do: Serve the file with the Content-Type its bytes really are, or convert it to the type you declare. |
MEDIA_DRAINING | 503 | The server is shutting down and takes no new streamed calls or legs. Another server takes them.What to do: Retry in a moment. POST /v1/calls runs again under the same Idempotency-Key; a call action or a conference write stores this error against its key, so retry those with a new one. |
MEDIA_FETCH_FAILED | 422 | media.url did not answer with a file — no answer, a non-2xx status, a redirect or an empty file (reason; upstreamStatus for a non-2xx).What to do: Make the link answer 2xx with the file itself within 20 seconds — redirects are not followed — or upload it with POST /v1/media and send media.id. |
MEDIA_NOT_AVAILABLE | 409 | The file is still being fetched from WhatsApp (mediaStatus: "PENDING") or never will be (mediaStatus and failureCode say why).What to do: While mediaStatus is PENDING, retry shortly or wait for message.media.ready; otherwise do not retry — the file will not arrive. |
MEDIA_NOT_ENABLED | 503 | This deployment keeps no media, so files can be neither sent nor downloaded.What to do: Retrying will not help: send text or a template instead, or contact us. |
MEDIA_NOT_FOUND | 404 | GET /v1/messages/{messageId}/media on a message that carries no file; or a /v1/media upload id that is unknown, expired, deleted or another mode’s (a test key never sees a live upload).What to do: Check that the message carries a file (media on GET /v1/messages/{messageId}); for an upload, upload the file again with POST /v1/media (an id lasts 7 days) using a key of the same mode. |
MEDIA_REDIRECT_REFUSED | 502 | Fetching a WhatsApp media file: Meta answered with a redirect this API does not follow (off Meta’s hosts, or too many).What to do: Try again later; if it keeps failing, contact us with the requestId. |
MEDIA_TOO_LARGE | 413 | The linked file is over its type’s cap (5 MB for an image, 16 MB otherwise).What to do: Send a smaller or compressed file, under its type’s cap. The same file fails the same way. |
MEDIA_TYPE_UNSUPPORTED | 415 | The link serves a type WhatsApp does not deliver.What to do: Convert the file to a type WhatsApp delivers — see Media — and send it again. |
MEDIA_URL_REFUSED | 400 | media.url is not https on a public host; reason says why.What to do: Link the file over https on a public host, or upload it with POST /v1/media and send it by media.id. See Upload once, send by id. |
MESSAGE_NOT_CANCELABLE | 409 | DELETE /v1/messages/{messageId} on a message that is not a scheduled one still waiting for its sendAt — it is already being sent, sent, failed or canceled.What to do: Read the message (GET /v1/messages/{messageId}) to see where it is; a message on its way cannot be called back. |
MESSAGE_NOT_INBOUND | 409 | Only a message the contact sent can be marked read.What to do: Mark read only messages with direction: "inbound"; do not retry this one. |
MESSAGING_CONSENT_REQUIRED | 409 | A consent refusal not classified under a more specific consent code (reserved). Treat it like CONSENT_REQUIRED.What to do: Record the contact’s opt-in first (PUT /v1/contacts/{contactId}/consent/{channel}, once you have collected it), then send again. |
MESSAGING_PROVIDER_UNCONFIRMED | 504 | Meta timed out or failed (5xx) after a read receipt left.What to do: Send the read receipt again with backoff: a receipt creates nothing, so it is safe to repeat. |
MESSAGING_RATE_LIMITED | 429 | Meta is throttling — on template work or a read receipt.What to do: Retry after the retryAfterMs hint, backing off exponentially if it repeats. |
MESSAGING_SENDER_RESTRICTED | 409 | The sending WhatsApp number is restricted, disabled or quality-flagged; the SMS header is not active; or the email account is switched off in the console.What to do: Send from another sender (senderId; GET /v1/whatsapp/account shows each number’s status and qualityRating, GET /v1/sms/senders each header’s), or switch the email account back on in Settings → Channels → Email. A header becomes usable once the platform activates it. |
MESSAGING_TRANSPORT | 503 | The provider (Meta, the mail service or the SMS service) was never reached, or the SMS settings could not be read: nothing left Trovacast.What to do: Retry with backoff and the same Idempotency-Key: nothing was sent, so the key is released and the retry runs again. See Errors that changed nothing. |
MESSAGING_WINDOW_CLOSED | 409 | A WhatsApp text, media, interactive message or reaction outside the 24-hour customer service window — or the customer never wrote. See WhatsApp.What to do: Send an approved template instead (type: "template"), or wait for the customer to write. To answer a customer who wrote to another of your numbers, send with their conversationId. |
META_UNAVAILABLE | 503 | Meta could not be reached, or did not answer in time, for template work or the WhatsApp account. Nothing changed here, but a submit or an edit may still have reached Meta.What to do: After a submit or an edit, read the template — or run POST /v1/templates/sync — to see whether it reached Meta before trying again with a new Idempotency-Key (the same key replays this error). A delete, a sync or a read is safe to repeat. |
METHOD_NOT_ALLOWED | 405 | The path exists but does not take this HTTP method. The Allow header — and allow in the body — names the methods it does.What to do: Use one of the methods Allow names, and check the path against the API reference. |
MODEL_UNAVAILABLE | 422 | An AI agent names a model whose provider this deployment cannot run (no credentials are set up for it); provider, leg and model say which. GET /v1/models marks each model available.What to do: Pick a model GET /v1/models marks available for that leg, and set it on the agent (PATCH /v1/agents/{agentId}) or in the request. See Choose models. |
NOT_FOUND | 404 | No such resource for this key: another project's id is indistinguishable from one that does not exist. Some endpoints name what is missing with a more specific 404 code; treat any 404 as not found.What to do: Check the id, and that the key belongs to the project and mode that hold it — a test key reads only test records, a live key only live ones. Do not retry unchanged. |
NO_NUMBERS_AVAILABLE | 409 | Nothing you can order is on sale in that country with that area code or prefix, type and capabilities — in the platform’s inventory or any carrier’s stock your plan prices. Unlike NUMBER_NOT_AVAILABLE (one number, taken) another area may have numbers. country and prefix are in the body.What to do: Order again with another areaCode (a neighbouring one, or none), drop type or sms, or search first with GET /v1/numbers/available. A refused order frees its orderId. |
NO_SENDER_AVAILABLE | 409 | There is nothing to send from: no WhatsApp number (or the conversation’s number was removed), no chosen number that can send, or no active SMS header that fits the template’s category.What to do: Connect a WhatsApp number (Settings → Channels → WhatsApp) or choose one that can send; for SMS, register a header of the kind the category needs — numeric for promotional, alphabetic otherwise — and send once the platform has activated it. |
NUMBER_CURRENCY_MISMATCH | 409 | The number is priced in a currency the organization's wallet does not hold.What to do: Pick a number whose currency in the search results is your wallet's, or contact us to have this one priced for your wallet. |
NUMBER_NOT_ASSIGNED | 409 | Only an assigned number can be routed — not one on hold, suspended or being released. See Phone numbers.What to do: Activate a held number first (POST /v1/numbers/{numberId}/activate), then set its route; a suspended number routes again once it is reactivated, one being released never does. |
NUMBER_NOT_AVAILABLE | 409 | The number is not in a state that allows this: someone else holds it (or you already hold it), it is quarantined after a release, or it is retired — or a release of a number already being released.What to do: Pick another number from a fresh search (GET /v1/numbers/available); retrying this one cannot succeed while it is held, quarantined or retired. A number you already hold is listed by GET /v1/numbers. |
NUMBER_NOT_PRICED | 422 | A carrier’s number your plan has no price for (that type in that country), so it cannot be ordered. Search shows it orderable: false.What to do: Order a number search shows orderable: true, or contact us to have that type and country priced on your plan. |
NUMBER_ORDER_CONFLICT | 409 | The orderId you sent was used for another request (a different number, place, reference or identifiers), or the number it bought is no longer yours — released, lapsed or refused by its carrier.What to do: Send the same request with that orderId to read its order, or a new orderId for a new order. |
NUMBER_ORDER_IN_PROGRESS | 409 | Another request with the same orderId is being placed right now. An order id never buys two numbers.What to do: Retry in a moment with the same orderId and request: the answer is that order, with its number. |
NUMBER_PENDING_COMPLIANCE | 409 | The carrier bought the number for you but holds it for its regulator’s review of the paperwork (some countries require it). It is on hold (pendingCompliance: true), not live, not charged and never lapses. It appears as pending.code on an order, and as the refusal of POST /v1/numbers/{numberId}/activate while the review lasts.What to do: Nothing to do but wait for number.updated: approved, the number is activated and charged (or waits on hold with why); rejected, it is handed back. Release it to give it up. |
NUMBER_RESERVATION_LIMIT | 409 | The organization already holds the maximum number of pending number requests — five, or two while its business still awaits verification.What to do: Activate a held number (POST /v1/numbers/{numberId}/activate), release a hold you do not want (POST /v1/numbers/{numberId}/release) or wait for one to lapse, then order again. An approved business verification raises the limit to five. |
NUMBER_SMS_UNSUPPORTED | 422 | The number cannot be an SMS sender: it has no SMS capability, or it is Indian — SMS in India is sent from a DLT header, not a long code.What to do: Choose an SMS-capable number outside India (GET /v1/numbers?capability=sms); to text India, send from a DLT header instead. See SMS. |
NUMBER_SUPPLIER_ORDER_FAILED | 502 | The carrier did not complete the purchase of a held supplier number, so nothing was charged and the number stays on hold. It appears as pending.code on an order.What to do: Read the number for its new version and activate it again with a new Idempotency-Key (the same key replays this error), or release the hold, which drops it. |
NUMBER_SUPPLIER_ORDER_IN_PROGRESS | 409 | Another request is buying this held number from its carrier right now. A number is never bought twice.What to do: Retry in a moment, with the number’s current version (GET /v1/numbers/{numberId}). |
NUMBER_SUPPLIER_UNAVAILABLE | 422, 502 or 503 | 422: the carrier that supplies this number cannot provision numbers through its API on this deployment — the platform imports such numbers instead. 502: ordering or activating a carrier’s number, the carrier could not confirm the number in its stock right now. 503: a search (GET /v1/numbers/available) could search nothing — every carrier it asked failed and the inventory has nothing that matches (suppliers and retryAfterSeconds in the body; a carrier missing from an answer that has numbers is a warnings entry with this code instead), or an order named a carrier that cannot sell numbers through its API on this deployment.What to do: On a 502, or a search 503, retry shortly — an order with a new Idempotency-Key (the same key replays this error); nothing was held or charged. To search only the platform’s own stock, pass includeSupplierStock=false. On a 422 or an order 503, pick a number from another source, or contact us to have it imported for you. |
NUMBER_VERSION_CONFLICT | 409 | The number changed since you read it: another request routed, labelled, activated or released it, or its price changed while it was on sale.What to do: Read it again (GET /v1/numbers/{numberId}, or search again for one on sale) and retry with its new version — after checking the price, if it moved. |
ORGANIZATION_CLOSED | 409 | The organization is closed: it can be neither suspended, reactivated nor changed (PATCH /v1/organizations/{organizationId}), and a closed subaccount takes no transfer.What to do: Do not retry: closing is final. |
ORGANIZATION_ERASING | 409 | POST /v1/organizations named an externalReference whose organization is being erased.What to do: Retry once the erasure finishes: the reference then provisions a new organization. |
ORGANIZATION_NOT_ACTIVE | 409 | The project is not active (suspended or closing): a broadcast cannot start or resume, and an integration cannot act for it (Trovacast-Organization).What to do: Retry once the project is active again: whoever holds the suspension lifts it — contact us if it is ours. A closing project does not come back. |
ORGANIZATION_SUSPENDED_BY_PLATFORM | 409 | Trovacast or a partner holds the organization's suspension; an integration can lift only its own.What to do: Do not retry: ask whoever holds it — suspendedBy on GET /v1/organizations/{organizationId} says — to lift it; contact us when it is the platform. |
OWN_PHONE_IS_CARRIER_NUMBER | 400 | POST /v1/phones named one of the organization’s own business numbers. Nothing answers a carrier number when it is dialled, so it cannot be a staff handset.What to do: Register the handset your staff actually answer. To present a business number as caller ID, pass it as from or callerId instead. |
OWN_PHONE_LIMIT_REACHED | 409 | The organization already holds as many own phones as it may (200 unless this deployment sets another).What to do: Remove phones nobody answers any more with DELETE /v1/phones/{phoneId}, or ask the platform to raise the limit. |
PAYLOAD_TOO_LARGE | 413 | The request body is larger than the endpoint accepts.What to do: Send a smaller body: JSON bodies take at most 100 kB, except POST /v1/messages (12 MB), and an uploaded file is capped by its type (a verification document at 10 MB). The same body fails the same way. |
PAYMENT_REQUIRED | 402 | Billing refused the action. A more specific BILLING_* code usually replaces it.What to do: Check the balance and subscription with GET /v1/balance, top up (POST /v1/balance/top-ups) or settle the subscription in Settings → Billing, then retry. |
PHONE_NUMBER_MALFORMED | 400 | The path of GET /v1/lookup/{phone} is not a phone number Trovacast can read: letters, no country calling code, or a code no country uses. The message never repeats what you sent. A number that reads but is not one its country assigns is not this error — it is 200 with valid: false. See Lookup.What to do: Send the number in E.164 — + and its country calling code (%2B for + if your client rewrites it) — or write it nationally with ?country=; the same path fails the same way. |
PLAN_NOT_OFFERED | 409 | The plan is not one your integration may give its organizations: not on its partner's list, or — for an integration bound to no partner — not its default plan. planId names it.What to do: Name a plan your partner offers, or leave planId out for your integration's default plan. Offering other plans is the platform's to arrange: contact us. |
PORT_LOA_REQUIRED | 422 | loaDocumentId is not a letter of authority (number_loa) your organization uploaded to its business verification.What to do: Upload the letter of authority (POST /v1/verifications/{verificationId}/documents, type number_loa) and send its document id as loaDocumentId. |
PORT_NUMBERS_NOT_ASSIGNED | 409 | A port request is completed only once every number is live on the platform and assigned to the organization; the message lists the ones still missing.What to do: Nothing to change on your side: the request completes once the listed numbers are assigned to you. Follow it with number.port_request.updated. |
PORT_NUMBER_ON_PLATFORM | 409 | A number in the request is already on the platform (yours or another organization’s), so it cannot be ported in. The message lists which.What to do: Leave the numbers the message lists out of the request and send it again. |
PORT_OUT_INVALID_TRANSITION | 409 | The port-out is not in a state that allows this: it already completed, failed or was cancelled.What to do: Read the port-out (GET /v1/numbers/port-outs/{portOutId}); to move the number again, unlock it again. |
PORT_OUT_NOT_OPEN | 409 | The number is not being ported out (never unlocked, or its port-out already completed, failed or was cancelled), so there is nothing to relock.What to do: Nothing to do: the number is locked. GET /v1/numbers/port-outs?numberId= shows its port-outs. |
PORT_OUT_NUMBER_NOT_PORTABLE | 409 | Only a number you hold, assigned or suspended, can be unlocked for another carrier — not one on hold or being released.What to do: Activate a held number first, or port out another; a number being released is no longer yours to move. |
PORT_OUT_VERSION_CONFLICT | 409 | The port-out changed while your request was being answered (a new PIN, the carrier's word, the PIN's expiry).What to do: Read the port-out again and retry. |
PORT_REQUEST_DUPLICATE | 409 | A number in the request is already in another open port request of yours.What to do: Cancel that request (POST /v1/numbers/port-requests/{portRequestId}/cancel) or wait for it to finish — or leave the number out of this one. |
PORT_REQUEST_INVALID_TRANSITION | 409 | The port request cannot move that way: a completed, rejected or cancelled request is final.What to do: Do not retry: create a new port request (POST /v1/numbers/port-requests) if the numbers still need porting. |
PORT_REQUEST_VERSION_CONFLICT | 409 | The port request changed since you read it.What to do: Read it again (GET /v1/numbers/port-requests/{portRequestId}) and retry with its new version. |
PRODUCT_LINE_NOT_OFFERED | 409 | A product line your integration's organizations may not have: its partner does not offer it, or the integration is bound to no partner and it is calling. line names it.What to do: Leave the line off (switching one off is always allowed). Calling for your organizations is the platform's to arrange, by giving your integration a partner that offers it: contact us. |
PROMOTIONAL_NUMBER_REQUIRED | 422 | A call declared PROMOTIONAL must be placed from one of the organization's assigned 140-series numbers.What to do: Set from to one of your assigned 140-series numbers (GET /v1/numbers), or declare another purpose when the call is not promotional. |
PROMOTIONAL_PURPOSE_REQUIRED | 422 | A 140-series caller ID may place only calls declared PROMOTIONAL.What to do: Use another number as from for service or transactional calls, or send purpose: "PROMOTIONAL" when the call is promotional. |
PROMOTIONAL_WINDOW_CLOSED | 422 | Promotional calls are allowed only between 09:00 and 21:00 in the called party's time zone.What to do: Place the call again inside the window; the message names the called party's time zone. |
QUEUE_CLOSED | 409 | A transfer named a call queue that is switched off; it takes no callers. Nothing changed on the call.What to do: Switch the queue on (PATCH /v1/queues/{queueId} with active: true), or transfer to another queue. |
QUEUE_IN_USE | 409 | The queue cannot be deleted while a number routes to it, a campaign feeds it, a caller waits in it or another queue overflows into it. See Call queues.What to do: Move those first — route its numbers elsewhere (PATCH /v1/numbers/{numberId}), point other queues’ overflow away from it, let waiting callers be served — then delete it again. |
QUEUE_NAME_TAKEN | 409 | Another call queue of the organization already has that name.What to do: Choose another name, or change the existing queue instead (PATCH /v1/queues/{queueId}). |
QUEUE_NOT_FOUND | 404 | A transfer’s to.queueId names no call queue of this organization. Nothing changed on the call. On /v1/queues/{queueId}: no queue of this organization (with an active team) has that id. See Call queues.What to do: Pass a queueId from GET /v1/queues. |
QUEUE_VERSION_CONFLICT | 409 | The queue changed since the version you sent (its settings or its members).What to do: Read it again with GET /v1/queues/{queueId} and retry with its new version. |
RATE_LIMITED | 429 | Too many requests. Also a webhook test past its endpoint's budget, or a webhook URL past the project's hourly budget. See Rate limits.What to do: Wait Retry-After seconds, then retry the same request — with the same Idempotency-Key on a write — backing off exponentially with jitter if it repeats. See Backing off. |
READ_RECEIPT_EXPIRED | 409 | The message is older than WhatsApp’s 30 days for read receipts.What to do: Do not retry: WhatsApp no longer takes a read receipt for it. Mark messages read within 30 days. |
READ_RECEIPT_NOT_CONFIRMED | 502 | Meta answered the read receipt without confirming it. The message may or may not show as read.What to do: Mark it read again (POST /v1/messages/{messageId}/read): a receipt creates nothing, so repeating it is safe. |
READ_RECEIPT_UNSUPPORTED | 409 | This message cannot be marked read (it is not an inbound WhatsApp message).What to do: Send read receipts for inbound WhatsApp messages only; do not retry this one. |
RECIPIENT_EMAIL_REQUIRED | 422 | An email to a contact who has no email address.What to do: Send with to.email when you know the address (the contact with it is used, or created), or reach this contact on another channel. |
RECIPIENT_PHONE_REQUIRED | 422 | The contact has no phone number: an SMS, or a WhatsApp authentication template to a contact known only by WhatsApp username. Also a message.failed code.What to do: Reach this contact on WhatsApp with a text or a utility or marketing template instead. If WhatsApp later shares their number, it lands on the contact by itself and the send works. |
RECORDING_CONSENT_REQUIRED | 409 | The call would be recorded — recording.enabled, or the organization records every call (the default) — and the request carries no recording.consentEvidence.What to do: Send recording.consentEvidence — source, text and capturedAt of the contact's agreement — with the call. See Recording and consent evidence. |
RECORDING_NOT_AVAILABLE | 409 | The call's recording is not stored yet, or storing it failed; status is pending, processing or failed.What to do: While status is pending or processing, ask again after call.recording.ready; a failed recording does not become available. |
RECORDING_NOT_CONTROLLABLE | 409 | The call is recorded by its carrier, which Trovacast cannot pause. record is available only on calls Trovacast records itself; a sensitive gather on such a call is refused — nothing is collected — because the digits would land in a recording nobody can stop (sensitiveGather: false in GET /v1/calls/channels). A flow’s sensitive gather fails its run with this as flow.cause.What to do: Do not retry on this call. Collect card numbers and PINs on a call that is not recorded, or on a channel whose sensitiveGather is true (it pauses the carrier’s recording for the gather). |
RECORDING_PAUSE_FAILED | 503 | A sensitive gather needed the carrier to pause its own recording of the call, and the carrier did not confirm it (it refused, could not be reached, or had no recording to pause yet). Nothing was collected and no prompt was played. A flow’s sensitive gather fails its run with this as flow.cause.What to do: Retry the gather shortly with a new Idempotency-Key (a call action stores this error against its key). If it keeps failing, collect the digits on a call that is not recorded. |
REPLY_TARGET_NOT_FOUND | 404 | replyToMessageId or reaction.messageId names no message this key can see — another project’s, or one of the other mode (a test message to a live key; a live one, or any on a live customer’s thread, to a test key).What to do: Pass Trovacast’s message id (the id from GET /v1/messages), not WhatsApp’s, or send without the quote. |
REPLY_TARGET_UNAVAILABLE | 409 | The quoted (or reacted-to) message belongs to another conversation, or WhatsApp has no id for it yet (still queued, or failed). A reaction’s target may also be over 30 days old, or itself a reaction.What to do: Quote or react to a message of the same conversation once it is sent — retry a still-queued target after message.sent — or send without replyToMessageId. |
REQUEST_REJECTED | 4xx | Any other client error the platform has no more specific code for.What to do: Act on its HTTP status and message: change the request before you retry, since a 4xx refuses before anything changes. |
RETURN_URL_NOT_ALLOWED | 400 | A connect session’s returnUrl is not an https URL on an origin this deployment allows.What to do: Use an https returnUrl on an allowed origin — contact us to have yours added — or leave returnUrl out. |
SANDBOX_NUMBER_NOT_ROUTED | 409 | A simulated inbound call (POST /v1/sandbox/inbound-calls) rang a sandbox number its route would not answer — reason says why: not_routed (the number routes nowhere), inbound_off, suspended or calling_disabled — as a carrier’s call to a live number would be refused.What to do: Route the sandbox number first — PATCH /v1/numbers/{id} with a route, or PUT /v1/numbers/{id}/route with a flow — or fix what reason names, then simulate the call again. |
SANDBOX_TEST_KEY_REQUIRED | 403 | A live key asked for something only the sandbox does — simulating a customer’s message or call (POST /v1/sandbox/inbound-messages, POST /v1/sandbox/inbound-calls) or deciding a sandbox 10DLC registration (POST /v1/sandbox/sms-registrations/review).What to do: Send it with a test key (tc_test_…, Mode Test in Settings → Developers). See Try messaging before KYC. |
SENDER_NOT_FOUND | 404 | A send’s senderId names no WhatsApp number, email sender or SMS header of this project.What to do: Use a senderId from GET /v1/whatsapp/account (numbers[].senderId) or GET /v1/sms/senders, or leave it out to send from the default sender. |
SERVICE_UNAVAILABLE | 503 | Temporarily unavailable.What to do: Retry with backoff — with the same Idempotency-Key on a write — until an answer is replayed. If it persists, contact us with the requestId. |
SETTINGS_VERSION_CONFLICT | 409 | The organization changed since the version you sent to PATCH /v1/settings/calls. See AI over the API.What to do: Read the settings again (GET /v1/settings/calls) and retry with their current version. |
SMS_DESTINATION_NOT_ALLOWED | 422 | The number is in a country this project does not text: the platform’s destination list (India, plus the countries the operator has enabled) and the project’s own choice decide. country is in the body (null for a number in no country).What to do: Retrying unchanged cannot succeed. If you should text that country, check the project’s own list in Settings → Channels → SMS, or contact us to have it enabled. |
SMS_HEADER_CATEGORY_MISMATCH | 409 | The header does not fit the template’s category: promotional SMS go from a numeric header, every other category from an alphabetic one.What to do: Pass the senderId of a header of the right kind (GET /v1/sms/senders), or send a template whose category fits the header. |
SMS_MMS_UNSUPPORTED | 422 | An MMS (type: "mms") to a number outside the United States and Canada, or on an SMS route that carries no MMS. country is in the body. India’s DLT routes carry no picture messages. Also a message.failed code when the route stopped carrying MMS after the message was accepted; nothing was sent.What to do: Retrying unchanged cannot succeed. Send the picture on WhatsApp (type: "media"), or send an SMS with a link to it. For a US or Canadian number whose route carries no MMS, contact us. |
SMS_NUMBER_ALREADY_ASSIGNED | 409 | The number is assigned to a campaign already (this one under another reference, or another one): a number is on one campaign at a time.What to do: Use the assignment you have (GET /v1/sms/campaigns/{campaignId}/numbers), or remove it (DELETE …/numbers/{assignmentId}) and assign the number again. |
SMS_NUMBER_NOT_ELIGIBLE | 422 | The number cannot be on a US 10DLC campaign. reason says why: not_assigned (it is not one your organization holds), sms_unsupported (it cannot text), not_us (10DLC is for US numbers), or not_hosted (the SMS provider that registers campaigns here does not hold it).What to do: Retrying unchanged cannot succeed. Assign a US, SMS-capable number you hold (GET /v1/numbers); for not_hosted, order the number through the platform, or contact us. |
SMS_OUTSIDE_SEND_WINDOW | 409 | A promotional SMS outside 09:00–21:00 IST (or the project’s narrower window); opensAt says when it could go. See SMS.What to do: Send again at opensAt, or send with "sms": { "deferUntilWindow": true } to have it held until the window opens. |
SMS_REGISTRATION_CLOSED | 409 | The brand a campaign would belong to was rejected, or the campaign a number would join was rejected or has expired: nothing more can be registered on it.What to do: Retrying cannot succeed. Read statusReason on the brand or campaign, register a corrected one under a new reference, and build on that. |
SMS_REGISTRATION_REFERENCE_CONFLICT | 409 | A POST /v1/sms/brands, /v1/sms/campaigns or /v1/sms/campaigns/{id}/numbers named a reference you used for a registration with a different body. A reference is the idempotency key: the same body again answers the registration it made.What to do: To read the registration back, send exactly the body you first sent (or GET it). To register something new, use a new reference. |
SMS_SENDER_ALREADY_REGISTERED | 409 | POST /v1/sms/senders named a header this project registered already (headers are compared upper case).What to do: Use the sender you have: GET /v1/sms/senders lists it with its id and status. If this was a retry of a request that timed out, the first attempt registered it. |
SMS_SENDER_CLAIMED | 409 | Another project holds that header: a header is one business’s across the platform. The answer never says whose. When the message says the platform will review both claims, your claim waits in its queue: sms.sender_contest.updated tells you when it is awarded to you, or dismissed.What to do: Retrying cannot succeed. Register a header of your own; if this one is registered to your business on DLT, let the claim stand (or contact us) — the platform releases the other sender or awards the header to you. |
SMS_SENDER_CONTESTED | 409 | Another project claims this sender’s header and the platform has not decided: the sender cannot be removed until it does (removing and registering it again would wipe the claim).What to do: Retrying cannot succeed until the platform decides. If the header is yours on DLT, contact us with your DLT registration; the claim is then dismissed and the sender is yours to keep or remove. |
SMS_SENDER_NOT_ALLOWED | 409 | The sender cannot carry an SMS to that country: an alphanumeric ID where the country allows none, a number from another country, or the vendor’s default where the country wants your own. country is in the body. See SMS.What to do: Pass a senderId the country accepts (GET /v1/sms/senders) — often one of your numbers there, made an SMS sender with POST /v1/numbers/{numberId}/sms-sender — or leave senderId out so the first sender that fits is used. |
SMS_SENDER_REGISTRATION_REQUIRED | 409 | The country (the United States and Canada, for example) takes SMS only from a registered number, and the project has none for it. country is in the body.What to do: Register one of your numbers in that country with the carrier (10DLC or toll-free verification), make it an SMS sender (POST /v1/numbers/{numberId}/sms-sender), and send from it once it is active. |
SMS_SENDER_REJECTED | 409 | The platform rejected this header for your project — it disabled your sender of it, or awarded the header to another business’s claim — so your project cannot register it again.What to do: Retrying cannot succeed. Register a header of your own. If the rejection was a mistake, contact us with your DLT registration: the platform can lift it, and you can then register the header as a fresh claim. |
SMS_TEMPLATE_REQUIRED | 400 | An SMS to an Indian number sent as type: "text": SMS to India are template-only, because DLT has carriers match every SMS against a registered text. Free text goes to numbers outside India. Also a message.failed code for a free-text SMS whose number turned out to be Indian.What to do: Send an approved SMS template with its DLT id (type: "template"). See SMS templates. |
STATUS_CALLBACK_SECRET_MISSING | 409 | A send or call carried a statusCallback before the project had a status-callback signing secret for the key’s mode.What to do: Create the secret once with POST /v1/status-callback-secret (scope webhooks:manage) and store it — it is in that response only — then retry. See Per-request status callbacks. |
SUBACCOUNTS_NOT_AVAILABLE | 409 | Your organization is managed by a partner or was provisioned by an integration, so its projects are created by whoever manages it, not as subaccounts.What to do: Do not retry: ask the partner or integration that manages your organization to create the project. |
SUBACCOUNT_INSUFFICIENT_BALANCE | 409 | The wallet paying for a subaccount transfer holds less than the amount (availableMinor says what it holds). Nothing moved.What to do: Transfer at most availableMinor, or top up the paying wallet first and retry. |
SUBACCOUNT_LIMIT_REACHED | 409 | Your organization already has the most subaccounts it may hold (limit: 10 by default, or your organization's own cap the platform set; closed ones count). See Subaccounts.What to do: Reuse one of your existing subaccounts (GET /v1/subaccounts); closing one does not free a place. Need more? Ask us to review your organization's cap. |
SUBACCOUNT_NESTING_NOT_ALLOWED | 409 | Your organization is itself a subaccount, and subaccounts go one level deep.What to do: Create the subaccount from the parent organization instead (POST /v1/subaccounts with one of the parent's keys). |
SUPPRESSION_FORCE_REQUIRED | 409 | Removing a complaint suppression needs ?force=true&reason=…. Removing it does not reopen the contact’s email consent.What to do: Only if the recipient asked for your mail again, repeat the delete with ?force=true&reason=…; both are recorded in the audit trail. |
TEAM_NOT_FOUND | 404 | teamId on POST /v1/queues names no active team of this organization. Nothing was created. See Call queues.What to do: Pass the id of an active team of the organization — the teamId of a queue GET /v1/queues lists is one. |
TEMPLATE_NOT_EDITABLE | 409 | PATCH /v1/templates/{templateId} on a WhatsApp template Meta will not edit now (anything but approved, rejected or paused — its status is in the body), one never submitted to Meta, an email template, or a test key’s template. See Templates.What to do: Wait until the WhatsApp template is approved, rejected or paused; submit one never submitted with POST /v1/templates; edit an email template in the console; delete a test template and create it again. |
TEMPLATE_NOT_FOUND | 404 | No template of this channel matches the id, or the name and language, the request named.What to do: Check the id, or the name and language, against GET /v1/templates for the channel you are sending on — a template belongs to one channel. |
TEMPLATE_NOT_SENDABLE | 409 | The template is not approved — pending review, paused, rejected, disabled or deleted, or an SMS template without its DLT id. Also a message.failed code when it changed after the message was queued.What to do: Send an approved template, or wait for Meta’s verdict (template.updated); give an SMS template its dltTemplateId with PATCH /v1/templates/{templateId}. A message that failed with this code was not sent: send it again once the template is approved. |
TEST_MODE_UNSUPPORTED | 422 | A test-mode key (tc_test_…) cannot perform this: either it has no sandbox — managing templates, the WhatsApp account or email domains, writing broadcasts, renting numbers — or it would read or change live data: a recording, a contact export, consent, changing or erasing an existing contact, or changing live call flows, applications and AI agents. (A live customer’s conversation, or a live message to quote or react to, is not refused but not found: 404.) See Authentication.What to do: Repeat the request with a live key (tc_live_…); no test key can do it. In test mode, work on the test records your test key created instead. |
TTS_UNAVAILABLE | 503 | Speech synthesis is not configured on this deployment, so speak (and spoken prompts) are refused rather than played as silence. Nothing was played.What to do: Use play with a WAV URL instead (a gather’s prompt.url likewise); retrying speak will not help on this deployment. |
UNPROCESSABLE | 422 | The request is well-formed but cannot be processed.What to do: Read message for what cannot be processed and change the request; retrying it unchanged fails the same way. |
UNSUPPORTED_MEDIA_TYPE | 415 | The request's Content-Type is not one the endpoint accepts.What to do: Send Content-Type: application/json with a JSON body — except the file uploads (POST /v1/media, POST /v1/verifications/{verificationId}/documents), which take multipart/form-data. |
UPLOAD_SESSION_REFUSED | 502 | Uploading a template’s header sample: Meta answered with an upload session this API will not address. Nothing was submitted.What to do: Send the request again with a new Idempotency-Key (the same key replays this error); contact us with the requestId if it repeats. |
VALIDATION_FAILED | 400 | The request is malformed; message lists each problem. Also a bulk webhook resend whose until is not after since.What to do: Correct every problem message lists, then send the request again; the same body fails the same way. The API reference has each endpoint's fields. |
VERIFICATION_DOCUMENTS_REQUIRED | 403 | This number type needs a document that is not on file and accepted yet — a letter of authority for 140-series, 160-series or toll-free numbers. Every organization needs it, including one an integration provisioned without a business verification.What to do: Upload the letter of authority (POST /v1/verifications/{verificationId}/documents with type number_loa, or Settings → Business verification); once the platform accepts it, activate the number again. |
VERIFICATION_INCOMPLETE | 422 | submitVerification: the verification is not ready for review — a required field, a document or a well-formed identifier is missing. missingFields, missingIdentifiers (identifiers still owed, by label — any one of a group's kinds will do), missingDocuments and invalid list what to add.What to do: Save what missingFields, missingIdentifiers and invalid name (POST /v1/verifications, identifiers in identifiers by the kinds GET /v1/verifications/requirements lists; with no entity type yet, choose it first), upload what missingDocuments names, then submit again. |
VERIFICATION_INHERITED_FROM_PARENT | 409 | This subaccount is the same business as its parent, so its business verification is the parent's — approved and revoked with it. It does not fill in or submit its own.What to do: Do not retry: complete the parent organization's verification instead, and read this one's state with GET /v1/verifications. |
VERIFICATION_REQUIRED | 403 | The feature (feature names it: numbers, live keys, live messaging, live calls or subaccounts) needs an approved business verification.What to do: Complete and submit the business verification (Settings → Business verification, or POST /v1/verifications then POST /v1/verifications/{verificationId}/submit), and retry once it is approved. See Business verification. |
VERIFY_CHANNEL_UNAVAILABLE | 422 | The channel cannot send for your project: no ACTIVE sender on it, more than one and no senderId, or a senderId that is not one of yours.What to do: Pass senderId of one of your active senders on the channel (GET /v1/sms/senders lists SMS ones, GET /v1/whatsapp/account WhatsApp numbers), or set the channel up first. |
VERIFY_DELIVERY_FAILED | 502 | The channel's provider did not accept the code. Nothing was billed; a first send's verification is canceled, a resend's stays pending.What to do: After a first send, start a new verification; after a resend, resend once the cool-down has passed. Use a new Idempotency-Key either way — the same key replays this error. |
VERIFY_DESTINATION_BLOCKED | 422 | Codes are never sent there: a premium-rate or shared-cost number, a high-risk international prefix, a destination your project's destination policy blocks, or an email address on your suppression list. See Verify → Fraud protection.What to do: Do not retry this destination: ask the person for another number or address, or verify them on another channel. |
VERIFY_DESTINATION_INVALID | 422 | to is not a phone number in E.164 (sms, whatsapp, voice) or an email address (email) — or it is not one its country assigns. See Verify.What to do: Ask the person for their number again and send it in E.164 (+ and the country code), or an email address for email. Do not retry the same to. |
VERIFY_NOT_PENDING | 409 | The verification is no longer pending — approved, expired, failed or canceled (status names which) — so it takes no check and no resend.What to do: Do not check or resend it again: start a new verification with POST /v1/verify if the person still needs a code. |
VERIFY_RATE_LIMITED | 429 | Too many verifications: 5 an hour or 10 a day to one destination, or 60 a minute or 10,000 a day for the project. The message says which.What to do: Do not retry at once: wait out the minute, hour or day the message names. Many codes to one destination are a sign of abuse — see Fraud protection. |
VERIFY_RECIPIENT_OPTED_OUT | 422 | The number's contact opted out of the channel with your project: a full opt-out (an SMS STOP, an unsubscribe, a complaint), or a marketing opt-out your project does not let codes pass. Nothing was sent or billed.What to do: Do not retry the same channel. Verify the person on another channel (email, voice), or — if the opt-out was from marketing only and your compliance rules allow a code the person asked for — turn on ignoreMarketingOptOut with PATCH /v1/settings/verify. A STOP is never overridden: the person can text START to opt back in. |
VERIFY_RESEND_TOO_SOON | 429 | A resend inside thirty seconds of the last code.What to do: Resend after retryAfterSeconds; meanwhile the person can still enter the code already sent. |
VERIFY_SEND_LIMIT | 409 | The verification has sent five codes already.What to do: Start a new verification with POST /v1/verify (and a new Idempotency-Key). |
VERIFY_TEMPLATE_INVALID | 422 | templateId is missing or cannot carry a code: SMS needs an APPROVED template with exactly one variable (to India a DLT TRANSACTIONAL template with its DLT id); WhatsApp needs an APPROVED AUTHENTICATION template.What to do: Pass the templateId of a template that fits (GET /v1/templates shows each one's status and category); create one and wait for its approval if you have none. See Send a code. |
VOICE_APPLICATION_IN_USE | 409 | Numbers still route to the voice application, so it cannot be deleted.What to do: Route those numbers elsewhere first (PATCH /v1/numbers/{numberId}), then delete it again. |
VOICE_APPLICATION_NAME_TAKEN | 409 | Another voice application of the organization already has that name.What to do: Choose another name, or change the existing application instead (PATCH /v1/applications/{applicationId}). |
VOICE_APPLICATION_VERSION_CONFLICT | 409 | The voice application changed since the version you sent.What to do: Read it again (GET /v1/applications/{applicationId}) and retry with its new version. |
WEBHOOK_DELIVERY_IN_FLIGHT | 409 | A resend of a delivery that is being attempted at this moment.What to do: Wait for the attempt to finish, then check the delivery (GET /v1/webhook-endpoints/{endpointId}/deliveries) and resend it only if it failed. |
WEBHOOK_ENDPOINT_DISABLED | 409 | A resend (one or in bulk) on an endpoint that is not enabled.What to do: Enable the endpoint first — PATCH /v1/webhook-endpoints/{endpointId} with status: "enabled" — then resend. |
WEBHOOK_ENDPOINT_LIMIT | 409 | The project already has the most webhook endpoints it may have (10).What to do: Delete an endpoint you no longer need (DELETE /v1/webhook-endpoints/{endpointId}), or subscribe an existing one to more events with PATCH /v1/webhook-endpoints/{endpointId}. |
WEBHOOK_URL_INVALID | 400 | The webhook URL is not allowed; reason says why: URL_INVALID, URL_NOT_ALLOWED, DNS_FAILED, ADDRESS_NOT_ALLOWED or PORT_NOT_ALLOWED. See Webhooks.What to do: Register an https:// URL with no credentials in it, on a public host that resolves to public addresses, on port 443, 80 or 1024 and up (not a database or other non-HTTP service port). The same URL fails the same way. |
WHATSAPP_CONNECT_UNAVAILABLE | 503 | Hosted connect is not configured on this deployment, or its session store is unavailable. No link was issued.What to do: Retry with backoff — with the same Idempotency-Key if you like: the key is released, not spent. If it persists, contact us. |
WHATSAPP_NOT_CONNECTED | 409 | No connected WhatsApp account — needed to submit, edit, delete or sync templates, to send a read receipt, and to create or resume a broadcast.What to do: Connect a WhatsApp account (or reconnect it in Settings → Channels → WhatsApp), then retry. |
WHATSAPP_SANDBOX_MIXED | 502 | A request on a sandbox WhatsApp account named a live Meta id. Sandbox and live WhatsApp ids never mix.What to do: Use the sandbox account’s own number, template or media id; the live id never works there. |
WHATSAPP_SANDBOX_NOT_IMPLEMENTED | 502 | The WhatsApp sandbox does not model this request. It works against a live account.What to do: Leave this request out of your sandbox tests, and exercise it against a live account. |
WHATSAPP_SANDBOX_TARGET | 502 | A request on a live WhatsApp account named a sandbox id (a sandbox number, template or media). Sandbox and live WhatsApp ids never mix.What to do: Use the live account’s own number, template or media id; the sandbox id never works there. |
META_<code> | 400 or 502 | META_<code>: Meta refused, under its own code — 400 for template work (the reason in message), 502 for a read receipt. On a failed message, failure.code uses the same family (META_131047, META_131026, …).What to do: For template work, change what Meta refused — message carries its reason — before retrying; a read receipt is safe to send again. For a failed message, see Failure codes. |