vocapableError registry
Every non-2xx response from the API is an RFC 9457application/problem+json body whose type URI points at a page in this registry at https://docs.vocapable.com/errors/{code}. The code is stable and machine-matchable: a changed meaning is a new code, never a re-pointed one. Branch on the code alone and treat the status as redundant confirmation. How to handle problems: see theerror-handling guide. Every code below is an anchor on this page (/errors#{code}) and links to its own page.
Two families of 5xx are worth knowing before you retry anything:503 means this deployment is missing a dependency it needsThe request may succeed later or on another environment. 501means the code path is not implemented here and retrying will never help until it ships. Neither is ever the caller's fault.
9.1 Transport, authentication, and tenancy
Raised on every surface, ahead of any resource logic.
unauthenticatedAbsent, malformed, unrecognized, revoked, or expired API key. One byte-identical body covers all five deliberately - "revoked" and "expired" are facts about a key that was issued, so a per-reason message would answer whether a token ever existed here - and the same body answers the/internalservice credential's refusals. The response carriesWWW-Authenticate: Bearer.401insufficient_scopeThe key is valid but does not carry the scope this endpoint declares (03-domain-model.md§Authorization lists the thirty). Also raised by the key-management routes when a caller tries to grant a scope it does not hold, or to revoke or rotate a key broader than itself.403tenant_suspendedThe credential is good; the tenant is notactive-suspendedorclosed, the only other valuesck_tenants_statusallows. A billing/compliance state, not a bad key, so it gets its own type.403mobile_rollout_disabledA valid native-device authority or browser PKCE request names a workspace that the deployment master or its explicit tenant mobile-pilot decision does not admit. The product remains fail-closed even if the account/membership itself is active.403forbiddenThe admin surface is not reachable from this address (IP allowlist, evaluated before authentication), and the generic 403 fallback.403not_foundNo route matches the path. Resource-level misses use the specific*_not_foundcodes below.404tenant_not_foundThe authorized admin company-operations lookup names no company. No company or financial state is changed.404subscription_expansion_not_foundThe requested upgrade quote does not belong to this workspace.404subscription_expansion_conflictThe upgrade needs commercial/source reconciliation, another purchase holds ownership, or the request key names a different target. Staff subscription-terms, commercial-status and subscription-override writes also return this when an unfinished purchase reserves the commercial source; neither the account change nor its audit write commits.409subscription_plan_change_conflictThe frozen renewal proposal, owner confirmation, existing commitment, complete provider billing source or paid successor is not proven. Recover the original operation or dismiss an undispatched proposal; no unknown provider request is repeated.409subscription_plan_change_not_foundThis original renewal proposal does not belong to the selected company.404method_not_allowedThe path exists; the method does not.405conflictGeneric conflict fallback for a framework-raised 409.409rate_limitedToken bucket exhausted for this key.Retry-Afterand theRateLimit-*headers accompany it.429request_failedFallback for any other framework-raised HTTP error, so no response escapes without a code.as raisedinternal_errorAn exception no handler claimed. Answered by the outermost layer, so the CORS allow-list headers are added by hand for an admitted browser origin (without them the portal reports a transport failure, not the 500) together withX-Request-Id; the traceback is logged under that id.500
9.2 Request shape: validation, filtering, pagination, idempotency
invalid_requestBody or query failed contract validation.errors[]names each field and its reason - this is the only code that routinely carries many entries.422invalid_filterAn unsupported field, operator, or value in a filter query param.errors[]names the offending field.400invalid_cursorThecursorwas not a verbatimnext_cursorfrom a previous response. Cursors are opaque; do not construct them.400idempotency_key_requiredThe endpoint requiresIdempotency-Keyand none was sent - the two where a duplicate costs money or dials a human twice.400idempotency_key_invalidThe key exceeds the length ceiling. A UUID is the documented shape.400idempotency_key_reuseThis key was already used for a different request - another endpoint, or a different body. A key identifies one request; send a new one.409idempotency_key_in_flightA request with this key is still running (or died between claiming the key and recording its result), so this one must not perform the side effect a second time. Retry in a moment.409
9.3 Agents, templates, knowledge packs, voice profiles
agent_not_foundNo agent definition of that id belongs to this tenant.404agent_version_not_foundNo published agent version of that id belongs to this tenant.404agent_use_case_immutableA published agent definition cannot changeuse_case. Calling purpose determines the consent floor for its immutable versions and any campaign already using them; create a new draft definition for a different purpose.409voicemail_message_uncomposableThe agent carries avoicemail_configthat composes no message. A drop is a regulated artificial-voice call and is composed from the AI-disclosure opener, the configured body, and a platform opt-out closing;errors[]names the element that refuses. Also raised at campaign launch when the pinned agent version composes nothing.409template_not_foundNo platform template of that id.404template_not_publishedThe template exists but isdraftordeprecated, so it cannot be instantiated.409eval_gate_failedPublish is blocked: no completed golden-transcript replay run has passed for this agent's exact current draft hash and revision, the queued/running/latest run did not pass, or the definition changed while publish acquired its lock.errors[]carries theEvalRunid when one exists.409conversation_release_qualification_requiredSales, staffing or recruiting publication lacks three complete passing real-model repetitions for the exact current draft, languages, corpus and resolved provider/model/endpoint. Run the operator routing-chain check.409conversation_evidence_missingA conversation action lacks actual caller-turn evidence or cites a turn the trusted runtime did not supply. Capture the caller response before submitting the action.422action_confirmation_policy_invalidPublication requested an unsupported owner confirmation policy for this workflow. The policy is selected by the service, not a tenant draft field.409objective_scoring_invalidPublish (or a release-gate request) is blocked: one or more objectives carry ascoringblock the survey scorer cannot read - unknown scale, mapping keys outside the scale's answer set,ordinalwithout a matchingpointscount, a scored question with noidor no question text, or duplicate objective ids.errors[]names every broken field (objectives[i].scoring.mapping, …).409compliance_profile_unresolvedPublishing or managed starter creation cannot resolve an owned compliance profile. The explicit profile is unavailable, or no company default exists; no policy is invented.409knowledge_pack_version_unresolvedPublish is blocked: the named knowledge pack has no compiled version to pin (noneready, or the pinned number does not exist).409receptionist_intelligence_version_unresolvedPublish is blocked: this receptionist owns a structured business-intelligence draft but no current immutable intelligence version. Review and publish the facts first; a live call may never follow the mutable draft.409receptionist_intelligence_not_foundThis receptionist has no structured intelligence document yet. Create one before adding source snapshots, previewing compact facts, or publishing an intelligence version.404receptionist_intelligence_requires_receptionistThe requested agent is not areceptionistuse case. Structured business intelligence is intentionally agent-owned and cannot become a second prompt system for another modality.422receptionist_intelligence_conflictA concurrent writer created or changed the receptionist's intelligence draft. Refresh the document and retry the edit.409receptionist_intelligence_compile_failedThe approved structured facts cannot be rendered into the bounded spoken-knowledge bundle. Correct the referenced location or reduce the facts; source documents themselves are never injected into a live prompt.409receptionist_intelligence_source_limitThe receptionist already has the bounded maximum number of immutable source snapshots. Consolidate or retire sources before importing another snapshot.422receptionist_intelligence_source_not_foundThe requested immutable receptionist source snapshot does not belong to this receptionist.404receptionist_intelligence_source_review_conflictThe immutable source snapshot already has an approve/reject decision. Capture a new snapshot if the source or the decision needs to change.409receptionist_intelligence_token_budget_exceededThe approved spoken-knowledge bundle exceeds the profile's tokenizer-measured live budget. Distill the approved facts before publishing.422receptionist_intelligence_source_reference_unresolvedAn approved FAQ or business policy cites a source snapshot that does not belong to this receptionist. Review its citations before publishing the immutable intelligence version.422receptionist_intelligence_source_reference_not_approvedA cited source snapshot is pending or rejected. Explicitly approve the snapshot after review, or remove its citation, before publishing the immutable intelligence version.422receptionist_intelligence_version_conflictA concurrent intelligence publish claimed the next version number. Refresh the draft and retry; no mutable facts were promoted by this request.409receptionist_intelligence_version_not_foundThe receptionist owns an intelligence document, but not the requested immutable version number.404receptionist_release_not_supportedThe release-readiness and rollback surface applies only to an inbound receptionist agent; use the normal agent-version controls for every other use case.409receptionist_release_input_changedA release gate's sealed prompt inputs no longer match the receptionist draft, pinned knowledge, or structured-intelligence version. Run a fresh exact preflight rather than publishing proof for a different request.409receptionist_release_qualification_requiredA receptionist publish has no passing exact live-model preflight or carrier-path canary for its sealed inputs. Complete both release gates before it can be promoted.409execution_profile_missingPublication was given a qualified execution route without an execution-profile digest. Qualify the complete route and generation configuration before publishing; an incomplete pin cannot identify the evaluated settings.409custom_webhook_catalog_invalidA granted custom action has an invalid stored definition. Correct it before requesting qualification; a release check cannot silently omit a configured action.409custom_webhook_catalog_missingA bound execution route was supplied for publication without the granted custom action catalog. Capture and qualify those definitions before publishing.409custom_webhook_catalog_changedThe custom action definitions changed after the release inputs were captured. Run a fresh check against the current catalog before publishing.409receptionist_release_not_qualifiedThe selected immutable receptionist version has not been qualified for live calls (or is draining). The control plane refuses to arm an AI route, and carrier ingress uses its deterministic spoken fallback instead.409rollback_target_not_foundNo earlier published receptionist version with a still-passing release gate is available for restore. Publish and qualify a replacement instead.409rollback_target_not_priorA restore target must be an earlier immutable receptionist version; the active version is not its own rollback target.409receptionist_rollback_incompatibleThe chosen healthy version would make a current answering-policy location selector, runtime route, or direct-handoff target unsafe. Update the policy or choose another compatible version.409rollback_target_not_healthyThe selected prior version no longer has a passing release-gate record, so it cannot be restored automatically.409receptionist_candidate_not_foundThe receptionist has no open (or, for a read, no recorded) release candidate. Stage one withPOST /v1/agents/{id}/receptionist-release/candidate.404receptionist_candidate_agent_qualifiedThe agent's active version isqualified(ordraining). The candidate path stages only a receptionist that has never been qualified; it can never replace or un-qualify a live version.409receptionist_candidate_agent_routed_elsewhereThe agent already answers another number, directly or through an answering policy. A candidate version would change what that line answers with, so route it away first.409receptionist_candidate_number_in_useThe chosen number already has an inbound route (another agent, a voicemail route, or an answering policy). A candidate is staged only on an unrouted number or on its own candidate line; a working line is never replaced.409receptionist_candidate_open_elsewhereThe agent already has an open candidate on a different number. Withdraw it before staging on another line.409receptionist_candidate_route_changedThe staged candidate is no longer the agent's active version on its own direct line (a route, version, or number changed). Stage a new candidate.409receptionist_candidate_canary_route_mismatchThe attached carrier-path canary was recorded against a different line, carrier profile, or ingress configuration than the candidate line has now. Run and attach a new canary, then qualify.409carrier_canary_draft_hash_mismatchThe retained carrier evidence belongs to different agent draft bytes. Qualify the current draft.409carrier_canary_eval_evidence_invalidThe referenced evaluation does not contain valid release evidence. A new valid evaluation is required.409carrier_canary_eval_not_foundThe referenced qualification evaluation is unavailable in this company.409carrier_canary_eval_not_live_preflightThe evaluation is not a live-model preflight; scripted coverage cannot replace it.409carrier_canary_eval_not_passingThe evaluation has not completed successfully. Resolve its failures before carrier qualification.409carrier_canary_line_not_ai_routedThe number's current receiving route does not support this AI qualification path.409carrier_canary_line_not_routed_to_agentThe selected line does not currently route to the exact agent being qualified.409carrier_canary_live_evidence_invalidThe retained live-model evidence is malformed or incomplete. Repeat the live preflight.409carrier_canary_live_preflight_unqualifiedThe live preflight lacks the required qualified execution evidence.409carrier_canary_manifest_mismatchCarrier proof and live-model evidence name different capability manifests. Requalify the actual serving configuration.409carrier_canary_nonphysical_proofSynthetic evidence cannot qualify a production phone route. An observed carrier call is required.409carrier_canary_policy_invalidThe selected number's answering policy cannot be validated for qualification.409carrier_canary_proof_identity_mismatchProof identity does not match the exact company, agent, evaluation and selected number.409carrier_canary_route_fingerprint_mismatchThe current carrier route differs from the route observed by the canary. Repeat qualification after configuration is stable.409receptionist_regression_requires_receptionistCustomer-authored release regression cases belong only to a receptionist agent; change or create the agent with thereceptionistuse case first.422receptionist_regression_case_not_foundNo regression case of that id belongs to this receptionist.404receptionist_regression_case_version_not_foundThe named regression case has no immutable revision with that version number.404receptionist_regression_case_limitThe receptionist has reached the bounded number of customer-authored regression cases. Archive or consolidate a case before adding another.422receptionist_regression_case_version_limitThe regression case has reached its bounded append-only revision limit. Create a replacement case if its assertion needs further iteration.422receptionist_regression_case_name_conflictAnother regression case for this receptionist already uses that name. Choose a distinct name or update the existing case.409receptionist_regression_case_version_conflictThe case changed after the client read it. Refresh its current immutable revision and retry with thatexpected_version.409receptionist_regression_case_archivedAn archived regression case cannot be edited. It remains readable as evidence but is excluded from later release gates.409knowledge_pack_not_foundNo knowledge pack of that id belongs to this tenant.404knowledge_pack_version_not_foundThe pack exists; that version number does not.404knowledge_pack_token_cap_exceededThe compiled pack exceeds the hard token cap owned by08-ai-quality.md. One rule, one code: the hand-authored version endpoint and the document upload both raise exactly this.409knowledge_pack_version_conflictA concurrent create claimed the same version number. Safe to retry - the retry increments from the winner.409knowledge_pack_over_budgetThe upload compiles inside the hard cap but over thebudget_tokensceiling the caller asked for. Raise the budget (up to the cap) or distill the sources;errors[]reports each document's token cost.409knowledge_upload_unsupported_formatThe uploaded document is not one of the accepted formats (pdf, docx, csv, md, txt) - by declared format or by extension.415knowledge_upload_too_largeA document (or the request's document set) exceeds the ingest size limits, before any parsing.413knowledge_upload_encryptedThe document is password-protected. The platform never attempts to guess or strip a password; remove it and upload again.422knowledge_upload_corruptThe bytes are not a readable document of the declared format (invalid base64, a broken archive, non-UTF-8 text, a mislabelled file).errors[]names the file.422knowledge_upload_no_textThe document parsed but carries no extractable text - an image-only scan is the usual cause, and OCR must run before it can become a pack. A refusal on purpose: letting it through would publish a pack silently missing exactly the facts the tenant uploaded.422voice_profile_not_foundNo voice profile of that id belongs to this tenant.404voice_profile_revokedA revoked profile can neither accept a new consent proof nor be re-approved; create a new profile and collect consent again.409voice_profile_not_approvedAn agent draft tried to pin a cloned voice whose consent review has not approved it. Self-serve upload makes pending profiles common; without this gate the failure would surface as the runtime'sunknown_voicerefusal at dial time. Pick a stock voice until the review completes.409voice_sample_invalid_audioPOST /v1/voice-profiles/{id}/sample-recording(or consent upload): the file cannot be used - not decodable, wrong container, not 16-bit PCM mono WAV, under 6 s, over 90 s, or below 16 kHz.detailnames the exact defect; nothing was stored.422voice_upload_too_largeOne voice upload exceeds the per-file cap (20 MB decoded). Nothing was stored.413voice_rights_attestation_stalePOST /v1/voice-profiles: the echoed version/SHA-256 of the Voice Rights & Consent Attestation is not the one this deployment serves - the document changed between render and signature. FetchGET /v1/voice-rights-attestationagain and re-collect the signature.409voice_consent_proof_requiredApproval was attempted with no stored signed release from the voice owner. The release is a precondition, never a follow-up.409voice_cloning_withdrawnSelf-serve voice cloning is withdrawn.410agent_clone_source_changedPOST /v1/agents/{id}/clone: the source agent'supdated_atno longer matchesexpected_updated_at. Refresh, review and clone again; nothing was copied.409agent_clone_source_invalidThe source agent's saved configuration no longer validates, so it cannot be copied into a draft. Update the source first.422agent_clone_knowledge_invalidThe source agent's knowledge sources or citations are incomplete, so the clone would carry unreviewable facts. Nothing was copied.422agent_draft_changedA draft edit (settings or voice assignment) named anexpected_updated_atthat is no longer current. Refresh the agent before saving again.409knowledge_pack_requiredA knowledge version was named without its knowledge collection. Send bothknowledge_pack_idandknowledge_pack_version.422voice_preview_consent_requiredGreeting preview: the owned voice profile lacks approved consent, so no audio is synthesized.422voice_preview_greeting_missingGreeting preview: the agent has no saved greeting for the requested language. Save a greeting first; previews never synthesize unsaved text.422voice_preview_greeting_lengthGreeting preview: the saved greeting is too long for a bounded preview. Shorten it or use a full test.422voice_preview_limit_reachedThe company's greeting-preview budget is exhausted for the current window. Recorded stock samples stay playable.429website_source_invalidWebsite-assisted knowledge: the address is not an allowed public HTTPS destination, or a reviewed answer's source no longer matches.422website_unreadableThe public website could not be read within the bounded fetch (redirect, size, type or content limits). Nothing was saved.422website_extraction_failedThe extraction model did not return grounded, source-quoted suggestions. Nothing was saved; retry or enter facts manually.502website_setup_owner_requiredPaid website setup requires the selected company's active owner and verified native session.403website_setup_not_foundNo website setup job exists in the selected company.404website_setup_conflictJob intent, review revision, allowance, owner, or lifecycle changed;errors[].reasonidentifies the conflict. No additional generation was dispatched.409demo_changedThe saved preview revision or original import request changed. Refresh before saving or starting audio.409demo_review_requiredSave and review your business answers before starting a microphone preview.409demo_source_changedA website answer must retain the original source URL and quoted evidence. Enter new unsupported facts as manual business answers.409demo_import_in_progressA bounded import for this verified account is still running. Resume its saved state or enter details manually.409demo_import_limit_reachedThis verified account used its two lifetime website import dispatches. Failures do not reset that allowance; manual answers remain available.429demo_session_limit_reachedThis verified account used its two lifetime microphone preview mints, each capped at 120 seconds. Reviewed knowledge remains available for ordinary setup.429managed_number_rental_conflictRental not found for this company, or its ownership, accepted terms, state or carrier confirmation requires review.404 / 409managed_number_qualification_conflictOwned-number setup is missing or its immutable request, owner, paid coverage, test allowance or existing probe evidence prevents a new qualification.404 / 409managed_number_rental_funding_requiredSettled eligible prepaid credit is insufficient for the explicitly accepted initial rental;required_minorandcurrencyidentify the required amount. No number purchase was submitted.409managed_number_rental_release_requiredUse the owner-confirmed managed rental release workflow; a local number status change does not stop carrier billing.409
9.4 Contacts, lists, and imports
contact_not_foundNo contact of that id belongs to this tenant (soft-deleted rows are gone for this purpose).404contact_already_existsA live contact with that E.164 already exists for this tenant; numbers are unique per tenant among non-deleted rows.409contact_owner_not_foundThe requestedowner_user_idis not a user in this tenant. A foreign user id is indistinguishable from an absent one, so assigning a contact can never create a cross-tenant owner link.404contact_phone_reconsent_requiredPATCH /v1/contacts/{id}refused a changedphone_e164. Consent proof is bound to one telephone identity and cannot move to another number; create a new contact with fresh evidence, then retire the old contact.409consent_captured_in_futurePOST /v1/contactsreceived a consent capture timestamp after the server's current time. Evidence must describe an event that already happened; correct the source record's timestamp and retry.422contact_list_not_foundNo contact list of that id belongs to this tenant.404contact_list_in_useDELETE /v1/contact-lists/{id}refused: a campaign still targets this list. A campaign's target is part of the record of what it dialed, so the list outlives the campaign;detailnames the campaign. Delete the campaign first, or leave the list in place - its memberships cost nothing.409contact_note_not_foundNo note of that id belongs to that contact in this tenant. Scoped to the contact, not just the note: a note id that exists under a different contact is a miss here, so the pair in the path is the identity.404contact_call_not_foundThe optionalcall_idfor a note does not name a call for that contact in this tenant. An absent call, a foreign call, and a different contact's call are deliberately indistinguishable.404import_job_not_foundNo import job of that id belongs to this tenant.404import_too_largeThe uploaded CSV exceeds the per-import size limit. Split the file.413import_mapping_invalidThe column mapping does not fit the uploaded file.errors[]carries the mismatch againstcolumn_mapping.422contact_timezone_unresolvedDialability cannot be answered because the contact has no resolved timezone, and quiet hours are evaluated in the callee's local time. Fail-closed: no verdict is guessed.409jurisdiction_unresolvedNo policy set governs this number at all, so there is nothing to enforce and no window can be computed.effective_policynever falls back to a federal floor and never invents a window, because inventing permission on the input most likely to be missing was the original defect.409jurisdiction_residual_gateA policy set governs this number and names its own hole. Raised byGET /v1/contacts/{id}/dialabilityand byPOST /v1/callswhen the resolved policy carries aresidual_gatenothing has cleared - a requirement the record cannot evaluate: a state registration, permit, bond or message filing (operating_authority); a live-human-first or natural-voice condition (call_architecture); or a fact about the callee we do not hold (evidence).409
9.5 Campaigns, scrubbing, consent, and DNC
campaign_not_foundNo campaign of that id belongs to this tenant.404production_key_requiredCampaign creation, editing, launch, pause, resume, and cancellation, plus a BYO caller-ID/routing mutation, require a post-promotionvcp_live_key. Avcp_test_key is deliberately confined to mock test calls: it may stage a draft BYO account but cannot create/activate/pool/route its numbers, select it as default, or change/re-verify a real-verified BYO account.403compliance_profile_not_foundThe campaign named a compliance profile that does not belong to this tenant.errors[]names the field.404scrub_run_not_foundNo scrub run of that id belongs to this tenant.404telephony_account_requiredNotelephony_account_idwas supplied and the tenant has no default account to fall back to.422scrub_requiredLaunch refused: the campaign has no scrub run covering its target, or the run has not finished.409scrub_expiredLaunch refused: the scrub run has gone stale past itsexpires_at. Re-run it.409scrub_unacknowledgedLaunch refused: the scrub report exists and is fresh but nobody has acknowledged it.409agent_not_publishedLaunch, ad-hoc call, or test call refused: the agent has no published version to pin. Drafts are never DIALED.409call_question_conflictPOST /v1/callsrefused: a per-call question reuses an id the pinned version's objectives already carry. Per-call questions are additive-only - overriding a gate-proven objective per call would bypass the publish gate - so there is no precedence rule, only this refusal.errors[]names each collidingquestions[i].id.409call_questions_unsupportedPOST /v1/callsrefused: the request carriesquestionsbut the pinned version does not grantrecord_survey_answer, so the answers would have no tool to record them - a silent no-op refused at launch rather than debugged after the call. Grant the tool and republish, or launch without questions.409draft_session_staleAbrowser_draftvoice-session token was redeemed after the draft changed: the token seals the exact draft content hash minted against, redemption recomputes it, and a mismatch refuses rather than running text the operator did not authorize. Open a new session to hear the current draft.409callback_in_pastA requested callback time is at or before now, so there is no future instant to schedule.errors[]namescallback_at.409callback_too_far_aheadA requested callback time is beyond the booking horizon.detailnames the horizon in days. Legacy callbacks use it as anot_beforefloor that calling rules may move later.409callback_confirmation_conflictThis call already has a durably confirmed callback. An equivalent request returns its original result; a changed time, confirming turn or other facts do not cancel or replace the existing attempt. Reconcile that attempt before promising a change.409telephony_account_unverifiedLaunch, ad-hoc call, or test call refused: the campaign'sTelephonyAccounthas not passed verification. An unverified account cannot dial.409outbound_caller_id_requiredAn ad-hoc live call's verified default BYO account has no active, tenant-assigned, carrier-confirmed voice number. The request cannot name a caller ID; configure one on the account and retry.409spend_cap_exceededLaunch refused: the tenant has spent its cap for the current period. The detail names the amount, the cap, the period start, and where the cap came from. Pacer governor #4 enforces the same fact per dial batch, andPOST /v1/callsowes callers the identical check - there is no side door (11-billing.md).409spend_state_unknownLaunch refused: the tenant has a spend cap and the period's ledger holds chargeable usage on a meter that reaches an invoice but that itsPlancarries nooverage_ratesentry for, so period-to-date spend cannot be established. The detail names the meter, the plan, and the period start. Fail-closed per11-billing.md§Enforcement - unknown spend state does not launch.409payment_past_dueA new campaign launch or ad-hoc live call is refused once a payment has been outstanding since day 7 of the delinquency ladder (11-billing.md§Dunning). Campaigns already running finish normally - a card failure never cuts a live conversation - and paying the outstanding invoice restores launches within minutes. The detail names how many days the balance has been outstanding.409managed_production_not_availableA campaign launch or ad-hoc live call resolved to amanaged(platform-owned)TelephonyAccount. Platform telephony carries paid test calls to verified numbers only until a written legal opinion clears managed production. Use a verified BYO subaccount.409campaign_not_launchableThe campaign's current status refuses a launch.409campaign_not_pausableOnly arunningcampaign can be paused.409campaign_not_resumableOnly apausedcampaign can be resumed.409campaign_not_cancellableThe campaign has already finished.409campaign_not_editableThe campaign has finished; its configuration is now history.409voicemail_drop_policy_invalidThe campaign's storedvoicemail_dropdocument cannot be read as a policy, so launch cannot tell whether this program leaves messages. Refused rather than defaulted to "off": a hand-edited row must not silently disarm a gate.409voicemail_callback_not_in_serviceThe campaign elects a voicemail drop, but the callback number the composed message names is not an active voice number on this campaign's own telephony account with a receiving agent configured. Publish proved the tenant owns the number; this proves a callee who rings it reaches someone.409agent_pin_immutableThe campaign has already launched. Every call it placed carries the version pinned at launch, so the agent pin cannot be moved underneath that evidence.409campaign_target_immutableA campaign's target cannot be changed: the scrub run authorizing the launch covers one contact list. Targeting another means a new campaign.409scrub_run_already_acknowledgedThe run has already been acknowledged; acknowledgment records an actor and a moment and is not repeatable.409scrub_run_incompleteAcknowledgment refused: the run has not finished.409scrub_run_expiredAcknowledgment refused: the run has gone stale.409scrub_totals_mismatchThe acknowledged totals do not match the run's. The acknowledgment attests to what the customer saw, so a mismatch means they saw a different report.409dnc_scope_not_writableOnlyinternal-scope DNC entries are tenant-writable; the federal and state datasets are platform reference data refreshed by ingestion.403dnc_expiry_not_supportedAn internal DNC entry may not carryexpires_at. Recording one withdraws the consent behind the number and sets the contact's do-not-call flag, and neither is restorable when a suppression lapses - an expiry would destroy consent evidence permanently and then return the number to dialable. Internal DNC is a suppression that persists.422consent_record_not_foundThe revocation names a consent record that does not belong to this tenant.404consent_contact_mismatchThe revocation names a different contact than the record it revokes.409consent_not_revocableThe consent record is notactive, so there is nothing to revoke.409disclosure_text_requiredA PEWC consent record requires the verbatim disclosure text shown to the consumer; PEWC without it is not PEWC.422contact_not_dialableThe number is suppressed and this request would contact it anyway. Raised today byPOST /messageson an internal-DNC hit, and specified in §1 and §3 as the refusal an ad-hocPOST /callsor a test call returns, withblocked_reasons[]inerrors[]. A refusal raised by a compliance-floor control is never waivable.409
9.6 Calls, analytics, billing, and exports
call_not_foundNo call of that id belongs to this tenant.404receptionist_purchase_conflictA reviewed connection price or subscription source changed, a request key belongs to another purchase, or unfinished work requires reconciliation. Recover the saved purchase or review a fresh quote before confirming.409receptionist_payment_method_requiredThe verified uncovered connection amount is positive and the customer has no default payment method. Add one in Billing before confirming; no purchase is claimed or collected.402receptionist_purchase_not_foundNo saved receptionist connection purchase of that ID belongs to this tenant.404receptionist_purchase_pendingSigned Stripe event recovery could not finish the original connection purchase. Ownership is retained and the event can be retried without creating another invoice or charge.503inbound_voicemail_not_foundNo inbound voicemail receipt of that id belongs to this tenant. It is intentionally distinct fromcall_not_found: a receipt exists before audio has been imported into a normal Call.404analytics_window_unboundedstartandendare both required. A window is never defaulted: guessing one for a report that costs partition scans would hide the cost from the caller.400analytics_window_invalidendmust be strictly afterstart; the window is half-open[start, end).400analytics_window_too_wideThe window exceeds the per-report ceiling (the partition ceiling, §2). For longer history, exportcontact_attemptsand aggregate downstream.400analytics_grouping_too_granularThe requestedgroup_bywould return more buckets than one report may emit. Narrow the window, drop a dimension, or filter to one campaign.400usage_window_too_wideTheoccurred_atwindow on the usage ledger exceeds the per-page ceiling. For bulk extraction, exportusage_events.400subscription_not_foundThis tenant has no subscription.404subscription_inactiveThe subscription is not in a state that permits the request: on campaign launch, the mirrored Stripe subscription isunpaidorcanceled, so new launches refuse immediately (past_dueis different - it follows the documented seven-day dunning grace beforepayment_past_dueblocks launches; existing conversations are never terminated by this gate); onPUT /v1/subscription/extra-sessionsandPUT /v1/subscription/receptionist-connections, any status outsideactive/trialingrefuses the add-on change until billing is resolved.409service_plan_requiredCampaign launch/resume or a live contact-bound call requires an outbound plan covering the pinned agent version and positive purchased outbound capacity for this company. Engage covers surveys/reminders; Workforce also covers staffing/recruiting; Sales also covers SDR/custom work. Receptionist-only, absent, unknown, unpaid or canceled subscriptions cannot authorize outbound production.409receptionist_plan_requiredInbound session redemption found no current paid receptionist access for this company. A recognized subscription class in active, trialing or past_due state must carry positive included or purchased inbound connections. Missing, unpaid and canceled subscriptions refuse before live-session activation, even if an earlier ingress read was cached.409wallet_not_foundThis tenant has no wallet, so it has no budget to read or set. A wallet is created by provisioning when the sandbox fee lands; a tenant without one predates self-service checkout.404setup_handoff_not_foundPOST /v1/setup-handoffs/{id}/acceptor/declinefor business information not on offer to this company: never offered to it, withdrawn, or already decided.404setup_handoff_pack_unknownTheknowledge_pack_idnamed on accept is not this company's collection. Save the facts throughPOST /v1/knowledge/website-importfirst.422customer_invite_not_foundPOST /v1/customer-invites/previewor/claimwith a token that opens no open invitation (never issued, revoked, replaced by a resend, expired, or claimed by another company). The same answer for each.404customer_invite_not_claimablePOST /v1/customer-invites/claimfrom a company with no active owner or admin at the invited address;detailnames the address, masked. Nothing is linked.409offer_not_foundPOST /v1/offers/previewor/redeemwith a token that opens no live offer: never issued, revoked, replaced by a new quote version, or expired. The same answer for each, so the endpoint reveals nothing about which.404offer_not_redeemablePOST /v1/offers/redeemfor an offer this company cannot use now;detailsays why (not yet accepted on the offer page, a negotiated price or custom term that needs a signed order, prices republished since it was written, already used for another company, or this company already subscribes). Nothing is bound.409subscription_existsPOST /v1/subscriptionon a tenant that already has one (uq_subscriptions_tenant_id). A plan change amends the existing subscription; it never opens a second. Also answered when a concurrent request won the constraint.409subscription_provisioning_pendingA priorPOST /v1/subscriptionhas a durable operation but its first Stripe outcome is unknown. The API will not submit another order: wait for the signedcustomer.subscription.createdwebhook to reconcile it, then refresh billing. This refusal is what prevents a retry after Stripe's idempotency-retention window from creating a second base-fee subscription.409subscription_provisioning_reconciliation_requiredDurable local and Stripe evidence is incomplete or contradictory, so the operation is frozen for billing review. Do not retry with a different plan or assume a new order is safe; no automatic duplicate subscription is created.409plan_not_purchasableThe published plan exists but carries nostripe_price_id, so nothing can bill through it. An operator wires the plan to a Stripe Price before it sells; no price is invented at checkout.409plan_metered_prices_unwiredThe plan's base-fee Price is wired but its metered Prices are not, so a subscription opened on it would invoice the base fee and never rate a single forwarded charge.409extra_sessions_not_purchasableExtra concurrent sessions have no Stripe price in this deployment:VOCAPABLE_STRIPE_EXTRA_SESSION_PRICE_IDis unset, so the $200/mo add-on cannot bill. Raised byPOST /v1/subscriptionwithextra_sessions > 0and byPUT /v1/subscription/extra-sessionsneeding a Stripe change. An operator wires the one licensed plan-independent Price before the add-on sells; no price is invented.409extra_sessions_not_applicableThe plan includes no concurrent outbound sessions, so the $200/mo add-on has nothing to extend: raised byPOST /v1/subscriptionandPUT /v1/subscription/extra-sessionsfor a positive target on a plan whoseconcurrency_limitis 0 - thereceptionistclass today. Inbound answering capacity is bought as receptionist connections atPUT /v1/subscription/receptionist-connectionsinstead.409extra_sessions_update_unconfirmedThe capacity operation is saved, but its provider outcome is not fully confirmed. Retry the requested quantity to reconcile it from a fresh provider read; a signed subscription webhook can also complete it. A matching quantity alone does not prove which operation applied.502extra_sessions_update_failedThe current provider subscription could not be safely verified before dispatch, or Stripe definitively refused the original session change. The detail distinguishes an unsent request from a provider refusal. Uncertain or malformed successful responses useextra_sessions_update_unconfirmedand preserve their operation record.502receptionist_not_purchasableThe AI receptionist's two licensed Prices are not both wired in this deployment:VOCAPABLE_STRIPE_RECEPTIONIST_BASE_PRICE_ID(the first connection) orVOCAPABLE_STRIPE_RECEPTIONIST_CONNECTION_PRICE_ID(each additional one) is unset, so inbound answering connections cannot bill.409receptionist_connections_update_unconfirmedStripe did not answer the subscription-item update, so whether the connection change applied is unknown. The local count is unchanged; the signedcustomer.subscription.updatedwebhook reconciles it. Refresh billing shortly rather than assuming the change failed - the request is safely retryable because the target is absolute, never a delta, so setting N twice is setting N and no ambiguous outcome can double a fee.502receptionist_connections_update_failedStripe definitively refused the connection change. The local count is unchanged, the reserved receptionist lane admits exactly what it admitted before, and the detail carries Stripe's refusal.502receptionist_connections_charge_declinedThe prepaid first month of the connections being added could not be collected, definitely: the tenant has no saved payment method on the Stripe customer, the instrument refused, or the PaymentIntent came back in a terminal non-success state. Raised byPUT /v1/subscription/receptionist-connectionson an increase only - a connection is prepaid a full month and is not reserved until that charge succeeds.402receptionist_connections_charge_authentication_requiredThe prepaid first month could not be collected because the card's issuer demands Strong Customer Authentication (3-D Secure and its equivalents): the instrument was not refused and there is nothing to replace, and no off-session request can perform the challenge.402receptionist_connections_charge_unconfirmedThe prepaid month's payment may or may not have been taken: Stripe did not answer, answered a success the adapter cannot parse, answered about a charge whose customer/amount/currency this request does not recognize, or reported the PaymentIntent asprocessing- a delayed instrument such as an ACH debit that has not settled.502receptionist_connections_racedAnother writer movedsubscriptions.receptionist_connectionswhile this request was deciding, so the compare-and-set inset_receptionist_connectionsrefused and nothing local changed. Raised byPUT /v1/subscription/receptionist-connections.409collection_method_change_conflictAnother capacity purchase, upgrade, or collection-method change owns this subscription; the request key names a different target; or the saved source no longer matches. Recover the existing operation before starting a new change. No new provider write is dispatched by the refused request.409credit_note_already_issuedThe same route against an invoice that already carries a credit note in thecredit_notesmirror. The route is a re-attempt, not an issuer - theinvoice.finalizedwebhook handler is the issuer - and Stripe permits credit notes summing to the invoice total, so an unguarded second press is representable at Stripe and would over-credit. What an operator does: nothing; the comp landed.409credit_note_not_compedThe same route against an invoice whose tenant'scommercial_statusis notcomped(nor aninternal/trialarrangement that credits).422credit_note_issue_unconfirmedThe same route when Stripe did not answer the credit-note creation - a transient or timeout class, not a definite refusal. Money may or may not have been credited and the local mirror has no row. Deliberately not retried in-band, on the same posture asreceptionist_connections_charge_unconfirmedabove.502deferred_balance_insufficientThe same route when the tenant's remaining deferred-revenue balance (sum(deposits) - sum(settlements)) does not cover the invoice'samount_remainingin full.409settle_out_of_band_unconfirmedThe same route when Stripe did not answer the invoice re-read or thepay_invoice_out_of_bandcall - a transient or timeout class, not a definite refusal. Whether the pay applied is unknown.502subscription_terms_unsignedThe same route with acustom,comped, orprepaidterms row carrying noorder_acceptance_id. It is the CHECK that makes a paperless deal of those shapes unrepresentable rather than merely refused, modelled oncommitment_reconciles. Nothing was written.422subscription_terms_below_floorThe same route with aminute_rate_minorbelow the $0.05/min publishable floor on a row carrying neither an explicit owner approval reference (thefloor_approval_refcolumn) nor apricing_memo_ref. It is the custom-path floor CHECK - the second enforcement point beneathrate_card._assert_publishable, which guards only the published card and can see no number agreed with one tenant.422design_partner_conversion_notice_missingAn operator tried to end a Comped Period - stop the Design Partner Credit and convert the tenant to the Conversion Price - and either no §6.4 sixty-day notice is recorded for that tenant or the recorded send date is fewer than sixty days before the requested Conversion Date.409invoice_write_off_not_permittedbilling.invoice.write_offinvoked against an invoice whose tenant'scommercial_statusiscompedorinternal.mark_uncollectiblebooks to Bad debt, which says cash was expected and the customer failed us; a comp says no cash was ever expected and the customer is in good standing.409invoice_not_open_for_out_of_band_paymentbilling.invoice.mark_paid_out_of_bandinvoked against an invoice that is notopen- draft, void, uncollectible, or already paid. What an operator does: read the invoice's current status. A draft has not finalized and cannot be paid; a void invoice is terminal and Stripe's own reference says voiding cannot be undone; an already-paid invoice needs no record.409promotional_grant_no_metered_itemsbilling.promotional_credit.grantrequested for a subscription carrying no metered items for the grant to apply to.409subscription_unmanagedPUT /v1/subscription/extra-sessionsorPUT /v1/subscription/receptionist-connectionson a subscription that carries no Stripe reference (a dev-seeded or externally provisioned row), so there is no subscription item to change. Same family asstripe_subscription_missing: the API refuses rather than guessing which Stripe subscription to mutate.409stripe_customer_missingThe tenant has no Stripe customer to subscribe or to credit. It is recorded when the sandbox fee is paid; a tenant provisioned outside self-service checkout has none, and a second customer is never created for one that may already exist.409stripe_subscription_missingThe tenant has a local subscription but it has no Stripe subscription id (for example, a dev-seeded or externally provisioned row). Stripe customer-portal cancellation and plan-change deep links refuse rather than guessing which Stripe subscription to mutate.409subscription_cancellation_review_requiredHosted cancellation requires an identified Stripe subscription and effectivemtmterms. Missing, custom or committed terms direct the customer to support for order/end-date review. This does not assert that an expired commitment renews; a recorded current conversion restores self-service access.409stripe_subscription_failedStripe definitively refused the subscription. The durable operation records that refusal but no local subscription is created; a later corrected request reuses the same operation and provider correlation rather than creating a second one.502stripe_subscription_incompleteStripe answered with a subscription carrying no item billing period, which the pinned API version places on the items. Confirm the account's pinned version matches the adapter's - a locally guessed period would disagree with the invoice.502stripe_credit_failedStripe refused the $49 sandbox credit. The local claim rolls back with the request, so the credit stays redeemable - retry rather than granting it by hand.502stripe_read_failedRaised onPOST /stripe/webhookonly, and its audience is Stripe rather than a customer: an inbound invoice or subscription event could not be re-read from Stripe because Stripe did not answer. The 503 is the point - a non-2xx is how Stripe is asked to redeliver, and the alternative is acknowledging an event whose invoice was never mirrored or whose lifecycle state was never synchronized.503export_job_not_foundNo export job of that id belongs to this tenant.404invalid_export_columnsOne or more requested columns are not exportable for that resource;errors[]names each.422export_too_largeThe extraction would exceed the per-job row cap. 422, not 413 - the request entity is tiny; it is the result that will not fit. Split it with filters.422api_key_not_foundNo API key of that id belongs to this tenant.404key_mode_escalationPOST /v1/api-keyswithmode: "live"from a test key.403unknown_scopePOST /v1/api-keysnaming a scope outside the catalog (03-domain-model.md§Authorization). Refused rather than stored: a key minted with an unknown scope appears to grant something, grants nothing, and surfaces much later as a confusing 403.errors[]names the field.422voice_profile_missingthe pinned agent version carries no voice, so there is nothing to speak with. Raised byPOST /v1/agents/{id}/voice-sessionbefore any socket opens; §9.9 keeps the identical code for the runtime's own bootstrap. Answering it in HTTP is the point - the alternative is a WSS1008with no body, which tells the operator only that "it didn't work".409disclosure_opener_missingthe pinned agent version carries no AI-disclosure opener. A floor control, so its absence refuses the session rather than degrading it - on the browser transport exactly as on the carrier one.409llm_chain_unresolvableno link in the agent's LLM routing chain is reachable from this deployment, so the session would connect to a pipeline with no model. A deployment fault, not the caller's.503sandbox_session_in_progressPOST /v1/agents/{id}/voice-session: this account already holds its allowed number of open in-browser sessions.Retry-Aftercarries the session ceiling in seconds, which is when the one in progress frees at the latest. A concurrency fact about the caller, so 409 - nothing is broken and no quota is spent.409sandbox_session_limit_reachedThe per-account in-browser session budget for the current window is spent.errors[]carrieslimit,windowandresets_at, andRetry-Aftercarries the wait, because waiting is the entire remedy.429sandbox_ip_limit_reachedThe same budget, counted per source address rather than per account - the ceiling that stops one network minting sessions through many accounts. Same body shape and sameRetry-Afterassandbox_session_limit_reached; a distinct code because the remedy differs (wait, versus wait and stop fanning out).429chat_daily_limit_reachedThe workspace's daily chat-turn budget is spent.Retry-Aftercarries the wait; chat turns are budgeted-free, and the budget is the bound that keeps them free.429chat_ip_limit_reachedThe hourly per-address chat budget is spent - the ceiling that stops one network chatting through many keys. Same remedy shape aschat_daily_limit_reached.429chat_turn_limit_reachedThe posted conversation exceeds the draft'sguardrails.max_turns(or the platform default). Start a new conversation; the server keeps no transcript to trim.409chat_guardrails_unenforceableThe draft'sblocklist_patternscannot be compiled into the Layer-2 screen (an invalid or oversized regex), so a chat turn cannot be screened the way a call would be. Fix the draft's guardrails first - the same defect publish lint refuses.422chat_upstream_failedEvery link in the resolved chain refused before streaming began. The chain is the draft's routed providers only - deliberately no hosted fallback: chat runs the platform's own model, reached from the control plane through the chat-plane base_url override (VOCAPABLE_CHAT_PROVIDER_BASE_URL_OVERRIDES_JSON), and a dead link refuses honestly rather than switching brains.502human_rep_not_foundNo human-rep destination of that id belongs to this tenant.404rep_group_not_foundNo human-rep group of that id belongs to this tenant.404rep_destination_in_useThe tenant already configured that E.164 handoff destination. One destination has one owner so a future carrier callback cannot resolve an ambiguous target.409rep_group_name_in_useThe tenant already configured a group with that name.409rep_user_not_foundThe optional linked portal user is not active in this tenant. A foreign user is never linkable to a handoff destination.422human_rep_not_availableThe rep is inactive or has transfers disabled, so it cannot publish a manual availability advertisement.409handoff_targets_unconfiguredPublish refused because the draft grantstransfer_to_humanbut has no immutable direct-rep target snapshot. Configure one or more active, transfer-enabled tenant reps first, then request a fresh release evaluation.409funding_amount_out_of_rangePOST /v1/billing/prepaid/funding-intentsnamed an amount below or above this deployment's declared manual-funding range. No Stripe Checkout Session or wallet credit was created.422prepaid_calling_requires_active_subscriptionManual prepaid credit is available only after this tenant has an active or trialing production subscription. It funds platform-managed, tenant-verified test calls only; it is neither sandbox credit nor BYO carrier credit.409funding_idempotency_conflictThe supplied manual-funding idempotency key already names a different amount or currency. Retry the original request, or choose a new key for a new Checkout Session.409funding_payment_pendingNative owner creation found another unfinished company payment.funding_intent_ididentifies the saved payment to inspect or resume. No new intent or provider session is committed.409funding_intent_expiredThe hosted Checkout page for this local manual-funding intent expired. Start a new top-up with a fresh key; an expired browser page is never reopened. A signed paid completion can still settle its exact intent if Stripe delivers it after expiry.409checkout_failedStripe refused creation of the hosted manual-funding Checkout Session. The local intent remains recoverable by its idempotency key, but no credit is settled until a signed completion arrives.502checkout_response_invalidStripe's Checkout response did not match the saved manual-funding intent's payment identity, company customer, amount, currency, mode, metadata, or expected hosted URL. The browser is not redirected to an unrecorded payment page, and no credit is issued. Contact support before replacing the payment.502funding_intent_conflictA Stripe Checkout Session could not be durably attached to its local manual-funding intent. Retry the same key so Stripe idempotency can recover the one safe page; no credit was settled.409auto_fund_amount_out_of_rangeThe requested automatic amount or calendar-month cap falls outside the authoritative bounds returned byGET /v1/billing/prepaid/auto-fund; no SetupIntent page or PaymentIntent was opened.422auto_fund_requires_active_subscriptionAutomatic prepaid funding is available only to an active or trialing production subscription. It does not make sandbox credit, BYO traffic, or production campaigns chargeable.409auto_fund_idempotency_conflictThe supplied setup idempotency key already records different customer-approved threshold, amount, cap, or consent terms. Retry the original setup or use a fresh key for newly displayed terms.409auto_fund_setup_pendingThe previous setup operation cannot safely be reused or attached. The customer must refresh its authoritative state and, where instructed, begin a new hosted setup; no prepaid credit was settled.409auto_fund_setup_failedStripe refused or returned an unusable hosted SetupIntent Checkout page. The configuration remains disabled and no off-session debit is attempted.502payer_transfer_conflictThe shared billing setup cannot be applied or canceled as requested: the review changed, a company is ineligible (discounts, manual tax rates, pending changes), a card is missing, or the move already started. The detail names the reason; no billing change was made.409
9.7 Telephony accounts, phone numbers, and pools
telephony_account_not_foundNo telephony account of that id belongs to this tenant.404managed_acquisition_not_foundNo number-setup operation with that ID belongs to the selected company. Refresh that company's setup state.404managed_acquisition_already_startedThis acquisition is no longer pending and cannot be cancelled through the pending-operation endpoint. Reconcile its carrier outcome before changing numbers; this does not authorize releasing an acquired resource.409managed_number_owner_requiredNumber selection and setup require the active owner of an active selected company.403managed_number_search_invalidChoose a supported US state or a three-digit area code; city searches also require a state. No inventory request or purchase was made.422managed_number_paid_receptionist_requiredA current paid receptionist allowance could not be established for the selected company. Review its subscription and payment evidence before choosing an included number.409credentials_not_acceptedcredentialswere supplied on amanagedelection. A managed account dials on the platform's own carrier relationship and carries no tenant credentials.422telephony_credentials_missingVerification was requested on an account with nothing stored to verify.409telephony_verification_unsupportedThe account's carrier has a registered adapter that can place calls but cannot answer the two onboarding reads - prove a credential pair, prove a number is the account's.503telephony_account_not_activeThe named telephony account exists and is notactive- it was suspended or removed from service - so no call may resolve a carrier through it.409telephony_credentials_rejectedThe carrier refused the stored credentials. 400 rather than 503: nothing about this deployment is missing, the secret itself is wrong or revoked, and the cure is re-supplying it.400telephony_provider_unsupportedThe account names a carrier this build registers no adapter for. Raised byadapter_factory_for, theADAPTER_FACTORIESlookup that is the dispatch since 2026-08-20 - it replaced the singleaccount.provider != TWILIO_PROVIDERcomparison that used to be the whole of it, and thedetailis byte-identical to what that comparison raised.503telephony_provider_not_conformantThe account names a carrier whose adapter exists but whose conformance gate is not green on the current build - offline Tiers 0–4 red in CI, or the Tier 5 live observation older than a quarter (22-carrier-integration.md§1.1).503telephony_capability_unsupportedRaised at campaign launch and at the answering/originate election, never mid-call. The adapter refuses rather than silently substituting an inventedmachine_end_*verdict, because silent degradation here means leaving a recorded message over a greeting that is still playing.409telephony_number_not_ownedThe caller ID is not in the carrier account's own inventory. A number the tenant does not hold at the carrier may not be presented, whatever this platform's records say.409inbound_voice_webhook_not_readyThis account is not a verified BYO Twilio account with vaulted credentials, so no inbound-Voice webhook URL is published for it. Managed and unverified accounts cannot become a voice ingress.409phone_number_not_foundNo phone number of that id (or E.164) is visible to this tenant.404phone_number_existsThat E.164 is already on the platform. Numbers are globally unique.409phone_number_not_assignableThe number cannot be put into service: it is already in service, or it is being released and must rest first.409phone_number_not_assignedThe operation needs a number in service under this tenant: releasing one that is not in service, or adding platform inventory to a pool.409inbound_voice_number_not_eligibleA non-null inbound route requires an active, assigned, carrier-confirmed voice number on this tenant's verified BYO Twilio account. Clear the route withinbound_agent_id: nullto remove stale configuration after release or verification loss.409inbound_voice_agent_not_readyThe selected receiving agent does not belong to this tenant or has no published immutable version. Publish it before enabling inbound routing.409inbound_voicemail_policy_not_eligibleThe selected published receiving agent does not carry the one-party recording policy required for inbound voicemail. Choose an eligible agent or retain the live-agent route; an all-party disclosure cannot be converted into recording consent here.409answering_policy_not_foundThe number is visible to this tenant but carries no answering policy. Raised byGET /v1/phone-numbers/{number_id}/answering-policyand byDELETEof the same path - a delete that removed nothing says so rather than answering204, because "already gone" and "never configured" are otherwise indistinguishable on the wire and only one of them means the caller is looking at the wrong number.404answering_policy_agent_not_readyPUT /v1/phone-numbers/{number_id}/answering-policynames an agent in anaistep that does not belong to this tenant or has no published immutable version. Publish it first. Proved once per distinct agent the document names, at write time rather than at answer time: a draft must not become callable by being written into a menu branch, and a signed carrier callback is the wrong place to discover it.409answering_policy_location_not_readyAnaistep names a stable location reference that the agent's current immutable receptionist-intelligence version cannot resolve. Publish compatible business facts first, or remove the location selector; a raw address or prompt fragment is never accepted in an answering policy.409answering_policy_rep_not_readyPUT /v1/phone-numbers/{number_id}/answering-policynames a rep in aring_humansstep that is not an active, transfer-enabled rep of this tenant. Every named rep must resolve, not merely one of them: the step renders as an ordered<Dial>over the reps in the order the document gives, so a single unresolvable rep is a caller ringing dead air partway down the list.409number_pool_not_foundNo number pool of that id belongs to this tenant.404number_pool_member_existsThat number is already a member of this pool.409verified_number_not_foundNo verified-number registration of that id belongs to this tenant.404verified_number_existsThe number already has a live (pendingorverified) registration for this tenant. Re-registration restarts only an expired one; a revoked number registers as a fresh row.409verified_number_not_pendingThe check named a registration with no code awaiting confirmation - it is alreadyverified, orexpired/revokedand must start over.409verified_number_code_invalidThe presented code does not match. Attempts are bounded; exhausting them expires the registration.409verified_number_code_expiredThe one-time code's window has closed; the registration is nowexpired. Re-register for a fresh code.409verified_number_attempts_exhaustedToo many wrong codes; the registration is nowexpired. Re-register for a fresh code. The invalid/expired/exhausted split is deliberate - unlike an API-key refusal there is no existence oracle to protect (the caller already proved tenancy), and each names a different next step.409test_call_destination_not_verifiedThe test call'stois not a currentlyverifiedVerifiedNumber of this tenant -pendingis a registration, not proof, andexpired/revokedno longer count. Register the number (POST /v1/verified-numbers→POST /v1/verified-numbers/{id}/check) first; a test call may only dial a number the tenant has proven it controls.409test_call_cap_exceededThe per-tenant daily Platform Test Call volume cap is spent: counted per UTC day over campaign-less non-mock attempts. Mock test calls (avcp_test_key) never raise it. The detail names the count, the cap, and the UTC reset instant.409
9.8 Messaging, calendar, and webhooks
message_template_not_foundNo message template of that id belongs to this tenant.404message_template_existsA template of that name and locale already exists.409message_template_not_activeThe template exists but is notactive, so it cannot be rendered into a send.409message_template_body_invalidThe template body carries a malformed placeholder.422template_variables_invalidThe supplied variables do not match the template's declared set.errors[]names each onemissingornot_declared, and the detail lists what the template declares.422phone_number_not_sms_capableThe sending number does not carry thesmscapability.409sms_delivery_failedThe carrier refused this specific message and retrying changes nothing - an unreachable landline, a handset that replied STOP, a number that cannot receive SMS. Nothing was delivered, and the caller must fix the destination rather than try again.502a2p_registration_missingA2P 10DLC registration is incomplete on the sending number'sTelephonyAccount. Weeks of lead time, surfaced at onboarding rather than discovered here (01-roadmap.md).409webhook_endpoint_not_configuredThis tenant has no webhook endpoint yet (PUT /v1/webhook-endpointcreates it).404webhook_target_not_foundNo custom-webhook target of that id belongs to this tenant.404webhook_target_existsA target with thatwebhook_idis already registered. The id is the spoken name the model calls it by, so two targets may not answer to one; PATCH the existing target or choose another id.409webhook_target_name_reservedThewebhook_idnames a platform tool. A target may not shadow the registry; the same refusal the runtime makes at bind time.422webhook_target_schema_invalidThe target's argument schema uses a construct the shared validator (vocapable_contracts.toolschema) does not enforce, or renders over the per-target prompt budget. Refused at registration because bind time would refuse it identically - a stored schema is always a bindable one. The detail names the offending keyword or the measured size.422webhook_target_url_invalidThe target URL is outside the delivery policy: not absolute https (plain http is allowed only forlocalhost/127.0.0.1outside production), carries userinfo, or - in production - is a private, link-local, loopback, or otherwise non-global IP literal. A registered target must not be a bridge into the deployment's own network.422calendar_not_connectedThe tenant has no active calendar connection, or its stored grant is gone from the vault. Re-run the OAuth consent.409calendar_reconnect_requiredGoogle no longer accepts the stored grant or required calendar access. Reconnect the calendar; no availability or booking result was returned.409booking_outside_bookable_hoursPOST /v1/calendar/eventsnamed a time the tenant's bookable-hours policy does not admit - outside its open weekday windows, inside its minimum lead time, or past its booking horizon. Enforced at booking and not only atcheck_calendar, becausebook_meetingtakes an arbitrarystart_timerather than a slot id and a caller can name a time the agent never offered.detailnames the rule that refused.409calendar_provider_errorGoogle refused or malformed this calendar request. No meeting was created; check the connection and request.502invalid_oauth_stateThe OAuth callback'sstatedid not verify - forged, expired, or minted for a different provider family. The callback carries no API key, so the signed, tenant-bound, 10-minutestateis its admission control; a state that fails for any reason activates nothing.400oauth_consent_deniedThe customer's admin declined consent at the provider.400appointment_conflictThat external calendar event is already recorded against a different call, so recording it again would double-book one booking across two calls.409
9.9 Non-customer surfaces
The /internal audience (the voice runtime's synchronous calls, authenticated by a service credential) and the telephony provider callbacks are excluded from the customer OpenAPI document and are not part of the public contract. They emit the same problem shape, and their codes are registered here so an operator reading a log line has one place to look.
idempotency_key_requiredA mutating tool call arrived without an idempotency key. No mutation path exists without one - including for MCP-provided tools. Same code as the/v1guard's, same rule.400voice_profile_missingThe pinned agent version carries no voice.409disclosure_opener_missingThe pinned agent version carries no AI-disclosure opener. The call does not proceed: the opener is a floor control, so its absence is a refusal rather than a degraded call.409llm_chain_unresolvableNo link in the agent's LLM routing chain is reachable from this deployment.503runtime_plane_unavailableThe runtime plane is not configured in this deployment.503
9.10 Agreements
GET /v1/agreements includes an additive nullable markdown field per document. The current registry supplies the exact UTF-8 source bytes identified by content_sha256, allowing the portal to display every document before its acceptance.
onboarding_incompleteRequired setup is missing: sandbox activation needs an eligible declaration/assessment and saved plan; inbound Receptionist declaration needs saved valid business details; an inbound-only company must complete its first eligible outbound assessment before buying or quoting an outbound upgrade.409validation_failedPATCH /v1/onboardingnamed astepand supplied no answers object of that name. Distinct frominvalid_requestbecause the body is individually well-formed - it is the cross-field agreement betweenstepand its payload that failed, which no field-level schema can express.422onboarding_not_foundThe signed-in account has no signup application.GET/PATCH /v1/onboardinganswer with it before the wizard has been started, which is what tells the portal to start one rather than resume.404tenant_not_provisionedPOST /v1/onboarding/api-keywas called by a signed-in human whose account carries no tenant yet - the fee is unpaid, or Stripe'scheckout.session.completedhas not landed. 409 rather than 404 because the cure is time, not a different request: retry once the receipt arrives.409api_key_already_issuedPOST /v1/onboarding/api-keyhas already handed this tenant its first key, and that secret is shown exactly once. The route is deliberately first-key-only - a general session-authenticated mint would duplicatePOST /v1/api-keysunder a browser cookie, which is a weaker credential than the API key that route requires - so the cure isPOST /v1/api-keyswith the key already held.409console_access_refusedPOST /v1/auth/console-keywas called by a session whose membership or whose workspace is not active. Fails closed for a suspended workspace, a deactivated member, and any legacy session shape that cannot prove either.403production_key_owner_requiredPOST /v1/onboarding/production-api-keyis not being called by the active owner of an active workspace. The owner/session check runs before activation lookup, so a member does not learn whether the workspace is live.403production_request_owner_requiredGET /v1/onboarding/production-readiness,POST /v1/onboarding/production-readiness/request, orPOST /v1/onboarding/production-activationis not being called by the active owner of an active workspace. The check runs before preflight reads, so another member cannot use this route as an oracle for subscription, agreement, or carrier state.403production_not_readyActivation or a review request did not meet every persisted requirement. Production billing must have an active or trialing subscription with a recognized service class; unpaid, canceled, past_due and unclassified subscriptions cannot newly activate. Owner and staff preflight use the same rule.409production_already_liveThe owner requested review after the onboarding application was alreadylive. No duplicate request is created; use the post-activation live-key handoff if a production credential is still needed.409production_application_movedPOST /v1/onboarding/production-activationbegan a clean-pass self-serve activation, but the onboarding application leftpaidbetween the readiness read and the guarded transition (a concurrent activation or staff promotion). Nothing was changed; re-read state and retry.409production_no_compliance_profileSelf-serve activation reached the scrub-waiver write but the tenant carries nocompliance_profilesrow to attest against (a corrupted tenant - provisioning writes exactly one and nothing deletes it). Activation is refused rather than completing into an unscreenable state; contact support.409production_not_activatedThe active owner has a provisioned workspace but production activation has not durably put that same onboarding application inliveat theproductionstep. No live secret was minted; complete the readiness path and retry.409production_api_key_already_issuedThis tenant's one-time post-activation live-key handoff already succeeded. The original secret cannot be recovered because only its hash is stored; use the live key already held by the workspace or rotate it through the normal API-key surface.409webhook_signature_invalidPOST /stripe/webhookcould not verify theStripe-Signatureheader against the configured signing secret - unsigned, wrongly signed, or outside the 300-second replay tolerance. 400 rather than 401 because there is no credential to re-present. A deployment with no signing secret refuses every webhook rather than trusting one.400workload_class_below_floorThe plan selected atPATCH /v1/onboardingsits below the class the compliance screen established for this applicant. A class is a ceiling, so buying up is allowed and buying below the screen's verdict is not. The wizard disables those options; this is what makes it a control rather than decoration.422onboarding_closedThe compliance screening for this signup application returnedblockedorneeds_review, and the application is closed. Every write to/v1/onboardinganswers with it thereafter - deliberately terminal, so a refused applicant cannot vary one answer at a time until something passes. Cure is a human, not a retry.409outbound_review_closedThe first calling declaration is already recorded. Reuse its saved evidence instead of submitting another declaration.409outbound_review_needs_supportThe stored calling review cannot be safely resumed. Retain the current record and contact support.409paid_live_edit_base_changedThe serving receptionist version changed after the draft was opened. Review the current version before applying changes.409paid_live_edit_draft_changedThe draft changed outside the saved wizard. Reloading does not authorize overwriting those changes.409paid_live_edit_number_changeA live receptionist edit cannot replace its serving phone number. Keep that number or use a separate number workflow.409paid_live_edit_release_requiredLive changes require explicit testing, review and release. The first-launch path cannot apply this draft.409paid_live_edit_requiredOpen an explicit draft before changing a live receptionist; draft writes must preserve its serving release.409paid_live_edit_test_in_progressA release candidate is being tested. Finish or withdraw it before editing the draft.409purchase_draft_changedAnother save changed the account-owned purchase revision. Reload the saved choices while retaining current inputs, then explicitly retry.409purchase_draft_invalidSaved purchase preparation cannot be decoded. Retain the record and contact support for recovery; do not replace it with blank choices.409purchase_journey_app_originThis application originated in the native companion. Continue its existing policy-compatible setup rather than creating a web purchase from it.409purchase_journey_existing_companyThis application already provisioned a company. Manage that company's subscription and agents instead of creating another acquisition order.409purchase_order_in_progressA dispatched acquisition order owns these choices. Resume or reconcile that order before changing the purchase. A browser cancellation alone cannot authorize a second subscription.409purchase_payment_pendingSigned acquisition payment notification requires read-only verification or reconciliation of the original order. Preserve its checkout identity and retry verification; this does not authorize another charge or grant service.503agreements_requiredThe tenant has not accepted the CURRENT version of every document needed by the surface.403agreement_version_mismatchThe acceptance names a version or content SHA-256 that is not whatGET /v1/agreementscurrently serves. An acceptance binds to the exact text presented (the jurisdiction-hash pattern); re-fetch and accept what is served.409agreement_draft_unacceptableThe named document still carries theDRAFT - FOR COUNSEL REVIEWbanner and this is production: no tenant may accept a draft. Dev/test deployments accept drafts so the flow stays testable. 503 because nothing the caller sends can succeed until the deployment's document set clears counsel review.503
9.11 First-party accounts and browser sessions
The portal's own sign-in. Sign-in refuses with one body for every reason - unknown email, wrong password, and a disabled account are invalid_credentials alike, because a per-reason message is an account-existence oracle on a surface with no credential to rate-limit against.
invalid_credentialsSign-in did not succeed. Unknown email, wrong password, an account with no usable password, and a session cookie carrying no synchronizer are one indistinguishable refusal on purpose.401google_credential_invalidThe Google ID token did not verify - expired, wrong audience, bad signature, and unknown issuer are one indistinguishable refusal on purpose; the reason goes to the security log.401google_email_unverifiedThe Google account's own email is unverified, so it cannot key a Vocapable account. Cure is verifying the address with Google, not a different request.403google_email_verification_requiredGoogle does not host this email address: its verified-email claim alone cannot prove current mailbox ownership. Use email/password sign-in, email signup, or password reset. No account is read, created, linked or verified, and no session is issued.403email_verification_requiredThe account exists and authenticated, but has not proved its email address, which onboarding requires before it can be started or paid for. Cure is the verification link, orPOST /v1/auth/email-verificationsfor another one - not a different request.403verification_link_invalidThe email-verification token is unknown, already consumed, or past its window. 400 rather than 401 because there is no credential to re-present: request a new link.400password_reset_link_invalidThe password-reset token is unknown, already consumed, or past its window. Same shape and same reason asverification_link_invalid, and a distinct code because the cure is a different flow.400csrf_token_refusedAn unsafe request carrying the session cookie presented noX-CSRF-Token, or one that is not this session's synchronizer. The token is served byGET /v1/auth/sessionand rotates with the session; refresh and retry.403csrf_origin_refusedAn unsafe request carrying the session cookie declared anOrigin/Refererthat is not a configured portal origin. Checked before the synchronizer so a cross-site attempt is refused without the response revealing whether the token would have matched.403company_selection_requiredThe signed-in account has several companies and did not name one. Choose a company before a company credential is issued.409company_setup_not_availableAdding a company requires an account owner or administrator with an opened first company.403company_setup_limitThe account already has the maximum number of unfinished additional-company setups. Finish or cancel one first.409invalid_onboarding_selectionA setup request named both, or neither, of an application and a company. Name exactly one.422onboarding_owner_requiredThe selected company setup belongs to a provisioned company whose active owner must finish it.403api_key_owner_requiredPOST /v1/onboarding/api-keyis not being called by the active owner of an active sandbox workspace.403free_receptionist_company_scope_requiredSelect this active owner's exact company explicitly; an account-wide or foreign application cannot supply Free progress.403free_receptionist_setup_requiredThe selected company lacks its current accepted Free offer and eligible original application, or already carries paid-purchase identity. Resume its original setup.409free_receptionist_progress_invalidThe saved company-owned Free stage is not recognized. Resolve that company's retained setup before advancing.409free_receptionist_terms_requiredComplete this company's terms step before confirming the $0 offer. Another company's progress cannot satisfy it.409
9.12 Account deletion
The verified, non-destructive account-deletion request/status path (/v1/account-deletion), one of the three session-cookie customer surfaces rather than a key-reachable one. A request opens a reviewable record; it does not erase a workspace or its call, billing, and compliance records.
account_deletion_email_confirmation_requiredPOST /v1/account-deletion/requestswas called on an account that signs in without a password, so a password cannot be the proof. Send a one-time confirmation link (POST …/email-confirmations) instead.409account_deletion_password_confirmation_requiredPOST /v1/account-deletion/email-confirmationswas called on an account that has a password, so the email link is not its proof. Re-enter the password on the account-deletion page.409account_deletion_reauthentication_failedThe password supplied to confirm the request did not verify. Enter the current Vocapable password and try again.403account_deletion_request_settledThis account-deletion request already reached a terminal outcome, so it cannot be re-confirmed. Open the status page to review the recorded outcome.409account_deletion_confirmation_invalidThe one-time email confirmation token is unknown, already spent, or expired (or its account is no longer active). 400 because there is no credential to re-present: request a new confirmation email.400
9.13 Mobile companion app (receptionist)
Company-wide agent authoring adds GET /v1/mobile/agent-knowledge, POST /v1/mobile/agents, and POST /v1/mobile/agents/{agent_id}/clone. All require the Admin-only AGENT_DRAFTS_WRITE capability and workspace_hub admission.
answering_policy_closed_steps_requiredA mobile schedule edit gave a number's answering policy business hours or holiday dates, but the policy carries no closed-step route to answer with when closed. Add a closed-step route before scheduling hours.422answering_policy_version_conflictThe answering policy changed after this mobile schedule edit was based on it (optimistic-concurrency mismatch on the policy version). Refresh the current policy and reapply.409appointment_not_foundNo appointment of that id belongs to this tenant.404emergency_forward_destination_invalidThe named human rep is not an active, transfer-enabled destination in this tenant, so it cannot be an emergency forward target. Choose an active, transfer-enabled rep.422emergency_override_expiry_invalidThe emergency-override expiry must be in the future and no more than 24 hours from now.422emergency_override_version_conflictThe emergency override changed before it could be cleared - the confirmation was for an earlier route. Refresh the current emergency route and retry.409handoff_booking_in_progressA calendar booking for this handoff is already running. Wait a moment, then reopen the handoff to see the booking receipt.409handoff_booking_not_foundNo handoff booking is available for this handoff and mobile role.404handoff_request_not_foundNo transfer (handoff) request of that id is available to this tenant or mobile role.404idempotency_key_conflictThe mobileIdempotency-Keywas already used for a different task action. Generate a new key before submitting a different update. Distinct from the/v1idempotency guard's codes.409mobile_availability_window_invalidThe availability duration must be in the future and no more than 12 hours from now.422mobile_billing_budget_version_conflictThe spend guardrail changed after the app loaded it. Reload the live budget, then start a new browser confirmation for the new revision.409mobile_call_ai_heldThe receptionist may not call this customer yet (E2-R11):holds[]says why in the person's words - most oftenai_consent_missing(no prior express written consent for marketing on the ledger; a teammate's review never counts), the calling window, or do-not-contact - withrequired_basisandwindow_opens_at.409mobile_call_ai_contact_search_too_shortThe Mobile Call AI contact search needs at least two characters; a phone number or email address is not a searchable label.422mobile_call_ai_transport_invalidMobile Call AI could not start on the verified business carrier route. Retry once that route is available.503mobile_capability_forbiddenThe signed-in mobile role does not carry the mobile capability this operation declares. Thedetailnames the required capability.403mobile_feature_disabledThe requested mobile feature is not enabled for this workspace's staged rollout. The browser portal remains the safe fallback.403mobile_invitation_delivery_failedThe team-invitation email could not be sent; no invitation was issued. Check email delivery and retry.503mobile_invitation_expiry_invalidThe invitation expiry must be in the future and no more than 30 days away.422mobile_member_not_foundNo editable team member of that id belongs to this workspace.404mobile_metrics_window_invalidThe receptionist-metricsendmust be strictly afterstart; the window is half-open [start, end).400mobile_metrics_window_too_wideThe requested receptionist-metrics window exceeds the maximum analytics span. Bound it to at most the allowed number of days.400mobile_metrics_window_unboundedReceptionist metrics require a bounded window: provide bothstartandend.400mobile_redirect_uri_refusedThe mobile return URI is not the exact claimed HTTPS or fixed iOS compatibility URI registered for this deployment.400mobile_rep_link_invalidThe selected transfer representative is not an existing rep owned by this workspace and unlinked elsewhere.422mobile_rep_link_requiredThis mobile membership is not linked to a transfer rep. Ask a workspace administrator to link it to a human rep.403mobile_self_membership_change_refusedAn admin cannot suspend, revoke, or change their own role from the mobile app. Use another active admin for the change.409mobile_founding_owner_change_refusedThe company's founding owner holds its original owner access; another member cannot change their role, suspend or revoke them from the mobile app. Contact support to transfer company ownership.409mobile_step_up_callback_refusedThe mobile step-up return address is not registered. Return to the app and start the confirmation again.400mobile_step_up_email_confirmation_invalidThe step-up email confirmation link is invalid or expired. Request another confirmation email.400mobile_step_up_email_proof_requiredThis account has no password, so the sensitive change must be confirmed from its verified email. Use the email confirmation option.409mobile_step_up_grant_refusedThe browser step-up confirmation can no longer be used. Return to the mobile app and confirm the change again.403mobile_step_up_native_context_refusedThis mobile session can no longer start a confirmation. Sign in again to continue in the app.401mobile_step_up_password_proof_requiredThis account has a password, so the sensitive change must be confirmed by re-entering it - not the email option.409mobile_step_up_payload_invalidThe protected step-up command is malformed. Return to the app and review the change before confirming it.422mobile_step_up_reauthentication_failedThe step-up password could not be confirmed. Enter the current Vocapable password and try again.403mobile_step_up_requiredA fresh browser step-up confirmation is required for this sensitive change. Confirm it in the browser, then return to the mobile app.403mobile_token_refusedThe mobile authorization (native token exchange) is not valid. Return to the app and start sign-in again.400mobile_profile_conflictThe personal profile changed or is no longer available. Reload it before saving; the name is shared across the account's companies.409mobile_transfer_destination_conflictThat transfer-destination phone number is already assigned to another representative. Choose a different number.409mobile_transfer_destination_delivery_failedThe transfer-destination verification code could not be sent; no change is pending. Check SMS delivery and retry.503mobile_transfer_destination_not_pendingThis transfer-destination verification is not pending. Start a new verification before submitting another code.409mobile_transfer_destination_rep_link_requiredLink the active team member to a human transfer representative before setting a transfer destination for it.409mobile_transfer_destination_verification_not_foundNo transfer-destination verification exists for this team member. Start a new one.404mobile_transfer_destination_verification_replacedThis verification code was superseded by a newer one. Request and confirm the newest code for this destination.409mobile_unauthenticatedThe mobile session is invalid or expired. Sign in again to continue in Vocapable Mobile.401mobile_workspace_selection_refusedThe chosen workspace is not one of the active workspaces available to the signed-in account.403operations_task_assignee_invalidThe chosen assignee is not an active member of this workspace. Choose an active member or clear the assignment.422operations_task_not_foundNo operations task of that id is available to this mobile role.404operations_task_state_conflictThat task action is no longer available in the task's current state. Refresh the task to see its current state.409operations_task_version_conflictThe task changed before this update (optimistic-concurrency version mismatch). Refresh the task and apply the change again.409mobile_change_feed_cursor_invalidThe change-feed position (cursor) is malformed or no longer valid. Restart the feed from the beginning, or from the last checkpoint you still hold.400mobile_coach_telemetry_role_invalidThe Coach telemetry role does not match the role currently granted to this mobile workspace session. Send the role this session actually holds.422mobile_receptionist_not_publishedThe receptionist has not been published yet, so it cannot be test-called from the Studio. Publish it first.409mobile_receptionist_studio_number_not_foundNo active receptionist line with that identifier belongs to this workspace.404mobile_receptionist_studio_intelligence_agent_invalidThe line-owned target is not a receptionist belonging to this workspace. Choose a receptionist target in the web control center first.422mobile_receptionist_studio_status_expiry_invalidThe temporary-status expiry must be in the future and no more than seven days from now.422mobile_receptionist_studio_version_conflictThe Receptionist Studio record changed elsewhere (optimistic-concurrency version mismatch). Refresh the receptionist details, compare the changes, and try again.409mobile_results_window_invalidMobile results: the requested period is malformed or longer than 31 days.422
9.14 Caller requests and the inbox
GET /v1/inbox also accepts equality filters agent_id and campaign_id, and created_at.lt for an exclusive upper bound. Existing created_at.lte remains inclusive.
caller_request_not_foundNo caller request of that id belongs to this tenant.404qualification_not_foundNo sales or recruiting qualification response of that id belongs to this tenant.404qualification_review_conflictCaller answers or the team review changed. Refresh the current response and review before submitting a new decision. A retry of an already saved idempotent request returns its original receipt.409contact_correction_not_foundNo proposed caller identity correction of that id belongs to this tenant.404contact_correction_conflictThe contact changed, a newer caller statement superseded the proposal, or it already has a final decision. Refresh before deciding. An idempotent retry returns its original saved decision.409caller_request_version_conflictThe request changed since it was read (optimistic-concurrency version mismatch). The detail names the current version; re-read the request and retry with it. Distinct fromcaller_request_invalid_transitionso a portal can tell "refresh and retry" from "someone already resolved this".409caller_request_invalid_transitionThe requested move is not one the state machine allows: acknowledge applies toopenrequests only, andresolvedis terminal for every edit, assignment included.409caller_request_assignee_not_foundThe namedassignee_user_idis not a user of this tenant. Theusers.idFK is global, so the tenant-scoped read is the control; pick an assignee fromGET /v1/users.404support_company_requiredThe selected company has no active user or membership for this signed-in account. Choose a company returned by/v1/support/companies; company suspension itself does not deny support.403support_ticket_not_foundNo support ticket is accessible in this selected company or staff intake scope. Cross-company tickets have the same response as missing tickets.404support_ticket_conflictA stale revision, changed idempotency payload, ineligible assignee, missing verified customer, or immutable customer-link conflict prevented the write.errors[].reasonstates which condition to resolve. Refresh and preserve unsaved text; do not blindly retry a changed request under the same key.409
9.16 The customer team workspace (`/v1/workspace/*`)
The customer's own CRM, worked by named people: every route requires the workspace:work scope and a console key that names a person (console_user_id); an integration key is refused with workspace_person_required even when it holds the scope. The company is the key's tenant; the role (owner / manager / rep) comes from the membership the key was minted under and decides every capability server-side.
workspace_person_requiredThis credential names no person in this company (an integration key, or a person whose user is no longer active).403workspace_capability_requiredYour workspace role does not include this action.capabilitynames the permission needed (reassign,approve,view_all_customers,refunds,pricing_override, …); ask an owner or manager.403stale_revisionThe record changed since you read it:expected_revisionis not its current revision (current_revisionsays which it is). Nothing was written; reload and reapply.409workspace_reference_invalidAn id you supplied (an owner, reviewer, primary contact, person) is not an active record of this company.errors[]names the field.422workspace_record_not_foundA workspace record of that id does not exist in this company, or you cannot open it.404workspace_organization_not_foundNo customer of that id that you can open. A rep opens the relationships they own or hold work in.404workspace_organization_existsA live business with that name (case- and spacing-insensitive) already exists - on create, or on a rename onto it.existing_organization_idnames it when you can open it, and is null when it belongs to a teammate's book. Nothing was created or changed.409workspace_timezone_invalidThe timezone is not an IANA zone name (for exampleAmerica/Chicago).422workspace_contact_not_foundNo person of that id that you can open (or not in the customer named in the path).404workspace_contact_phone_takenSomeone in this company already has that phone number (adding a person, or a customer with its first person).existing_contact_idnames that person, andexisting_organization_idthe customer they are filed under, when you can open them; both are null when they are in a teammate's book.409workspace_contact_point_not_foundNo contact detail of that id on that person.404workspace_contact_point_existsThat person already has that phone number or email (compared after normalization).409active_work_in_progressThe customer has a live reservation, or a call not yet through wrap-up, so it cannot be handed over (or its opportunity re-owned) now. Finish the call and wrap-up first.409workspace_task_not_foundNo task of that id that you can open.404workspace_task_anchor_requiredA task must name the customer, person or opportunity it is a promise about.422workspace_task_state_invalidThe task is not in the state this transition starts from (completing a done task, undoing an open one, cancelling a closed one).statussays where it is.409workspace_opportunity_not_foundNo opportunity of that id that you can open. A rep opens only opportunities they own.404workspace_draft_not_foundYou have no private draft for that purpose and record. Drafts are their author's alone.404workspace_reservation_not_foundNo reservation of that id is yours (a manager may also clear a teammate's).404workspace_reservation_endedThe reservation already expired or was released, so it cannot be renewed. Reserve the customer again before acting.409workspace_relationship_not_ownedA rep may reserve only customers they own; this relationship belongs to another teammate.403work_reservedSomeone - a teammate, you on another device, or an AI job - already holds the work on this customer.holdernames them,expires_atsays until when,next_actionsays what to do instead, andreservation_idis your own lease when the holder is you.409contact_policy_holdThe contact policy holds this contact now.409workspace_approval_not_foundNo approval request of that id that you can open (your own, or any if you may approve).404approval_self_reviewYou requested this; another owner or manager must review it (reassigning it to the requester is refused too).403approval_not_pendingThe request is no longer awaiting review, or it is assigned to another reviewer (reassign it first).statussays where it is.409approval_expiredThe request expired before it was reviewed; ask the requester to submit it again.409approval_staleThe approval no longer covers the action: the content changed since it was approved (its digest no longer matches), it expired, or it was already used.reasonsays which. Request a new review.409lead_import_not_foundNo lead import of that id in this company. Imports need thebulk_importpermission (owners and managers).404lead_file_unreadableThe CSV cannot be imported as a whole: larger than 1 MB, empty, more than 2,000 leads or 60 columns, a blank or repeated column name, or not CSV.reasonnames which; nothing was staged.422lead_import_mapping_invalidThe column mapping cannot be used: map a name or business column and a phone or email column, each column to one field.errors[]names each problem.422lead_import_state_invalidThe import is not at a step that allows this (mapping a committed list, deciding rows of a discarded one, committing one still being mapped).statussays where it is.409lead_import_row_not_foundNo row of that id in this import.404lead_import_row_settledThe row was already imported (resultsays how); change the customer itself instead.409lead_import_decision_invalidThe decision does not fit the row: linking to a person the row does not match, creating a person without a phone number, or importing an unreadable row.422lead_import_decisions_requiredAmbiguous rows are still waiting for a person to decide;awaiting_decisionsays how many. Nothing was committed.409lead_import_assignee_requiredThe list creates new relationships and nobody was chosen to own them. Existing relationships keep their owners.422lead_import_assignee_ineligibleThe chosen owner is not an active teammate of this company.422workspace_merge_invalidThese two customers cannot be merged (the same record, or the approval is for a different action).422merge_confirmation_requiredNobody else in this company can review the merge. Send it again withconfirm_without_reviewer: true; the confirmation is recorded as evidence.409merge_review_requiredAnother owner or manager can review this merge, so it cannot be self-confirmed. Ask for their review.409opportunity_stage_needs_lifecycleAn opportunity is created open (new,qualifiedorproposal). Record a sale, a loss or a deferral as a change to it, with the customer's acceptance, the reason or the return date.422opportunity_won_lockedThe sale's scope and value were accepted by the customer, so a stage, value or scope edit cannot move it. Open an amendment (POST …/amendments) or a follow-on opportunity (POST …/reopenwithmode=new); the accepted sale and its history stay.409opportunity_scope_acceptance_requiredRecording a sale needs the agreed scope and the customer's acceptance of it and the value (accepted_scope+scope_accepted: true). "Confirm the agreed scope and customer acceptance before recording this sale.".422opportunity_lost_reason_requiredA lost opportunity needs the reason the customer did not go ahead (lost_reason).422opportunity_deferred_date_requiredA deferred opportunity needs a futuredeferred_until. Its arrival makes the deal eligible to revisit; it never authorizes contact.422opportunity_reopen_reason_requiredA lost or deferred opportunity returns to an open stage only with areasonsaying what changed.422opportunity_not_closedOnly a won, lost or deferred opportunity can be reopened.409opportunity_not_wonOnly an accepted sale is amended; change an open opportunity directly.409handoff_plan_requiredRecording a sale opens its one delivery handoff: sendhandoffwith the recipient and the first delivery action.422workspace_handoff_not_foundNo delivery handoff (or prerequisite/milestone of it) of that id that you can open. A rep opens handoffs they send, receive, fall back for, or whose deal they own.404handoff_not_permittedThis handoff step belongs to someone else: only the recipient accepts, clarifies, declines and reports progress; only the sender answers or re-plans (the fallback owner too once it was declined or went unanswered); a manager may do either.403handoff_state_invalidNot possible at this stage of the handoff (responding to one that is not awaiting you, reporting progress before acceptance, completing a blocked or completed delivery, reopening one that is not complete).statussays where it is.409handoff_reason_requiredAsking for clarification, declining or marking a delivery blocked needs a message saying why.422handoff_prerequisites_openDelivery cannot start or complete while a prerequisite is open.open[]lists them.409handoff_payment_prerequisite_verified_onlyA payment prerequisite is satisfied when the payment provider confirms the customer's payment; only the company owner may record a payment received another way.409workspace_quote_not_foundNo quote (or link of it) of that id that you can open.404quote_invalidThe quote's money breaks a rule: no lines, a zero total, a discount above the subtotal, a tax amount under a treatment that has none, an included tax above the total, a deposit outside zero…total ("The optional deposit must be between zero and the quote total."), or an expiry in the past.reasonnames which.422quote_state_invalidThe quote cannot change this way: it was voided, or money was collected on it (refund it in the payment provider first).409pricing_policy_invalidA price floor needs both its amount and its currency.422merchant_provider_refusedThe payment provider refused the request.provider_codecarries its code.502hosted_payment_status_unknownThe original hosted-payment request may already have reached the merchant provider. Preserve its identity and inspect its status; another page or payment choice cannot authorize a replacement write. No paid result is claimed.503payment_reconciliation_requiredAn original payment is unresolved, processing or provider-confirmed paid. Reconcile that exact request before amending the quote; changing versions cannot hide or reset its financial authority.409
9.17 The customer team workspace on the phone (`/v1/mobile/workspace/*`, `/v1/mobile/voice/token`)
The native app reaches the same workspace records through thin wrappers authenticated by the mobile bearer (never a console key): the mobile role's capability (workspace_crm:read, workspace_crm:write, workspace_approvals:review, workspace_exceptions:read, workspace_integrations:read, workspace_calls:embedded) gates the native surface (mobile_capability_forbidden), and the workspace role mapped from the membership (admin → owner) decides every record exactly as §9.16 describes, with the same codes.
workspace_callback_not_futureA callback records a time agreed with the customer, sodue_atmust be later than now. Nothing was created.422workspace_voice_not_provisionedThis company has no verified phone account provisioned for in-app calling (telephony_accounts.workspace_voice_api_key_refandworkspace_voice_twiml_app_sid). Calls still reach people by carrier handoff; an owner sets in-app calling up on the web.409workspace_task_not_callbackOnly an agreed callback (kind = callback) takesPOST /v1/mobile/workspace/callbacks/{id}/reschedule|missed. Nothing changed.409workspace_call_link_invalidA record named for the call (task_id,opportunity_id,case_id,callback_id,missed_ticket_id) does not exist, is not yours to open, or is not about this customer - deliberately indistinguishable. Nothing was reserved, dialed or saved.404workspace_dnd_invaliddnd_untilmust be in the future and at most 7 days ahead (nullends do-not-disturb). Nothing was saved.422workspace_call_notes_not_foundNothing has been written on this call yet (or the wrap-up already used the notes). Save the first note withoutexpected_revision.404workspace_call_not_transcribedPOST …/transcript-tokenon a call that is not being transcribed;detailis the call's transcription label ("Not recorded - …").409workspace_ai_notes_not_readyNo AI notes exist on this call yet (the conversation has not produced a transcript turn).409workspace_ai_note_unknownA pin names a line no longer on the AI notes panel; read it again.422workspace_search_too_shortTranscript search needs at least two characters.422transcription_stream_refused/internal/workspace-transcription/*: the fork is unknown, closed, or its one-time credential does not match (deliberately indistinguishable).403workspace_voice_prerequisite_missingSetup needs a verified BYO Twilio account with a voice number first;voice_codesays which is missing.409workspace_voice_setup_failedTwilio refused or did not finish the setup; anything already created is reused on a retry.502workspace_voice_not_readyBrowser calling is not set up (or its key cannot be read);voice_codesays why.409workspace_call_in_progressYou already have a live call or an unfinished wrap-up;call_idnames it.409workspace_call_not_foundNo call of that id that you handle.404workspace_call_state_invalidThe call is not in a phase that allows this (hold only while talking, hand over only after the teammate joined, wrap-up only after the call ended).phasesays where it is.409workspace_call_already_wrappedThis call's outcome is already saved with different content; the same save again answers 200.409workspace_wrap_up_invalidNotes are required; a conversation or callback needs an agreed next step; a callback needs a future agreed time; a next step'snext_task_due_atmust be in the future; adealchange needs a linked deal; a call that left a voicemail drop is saved with outcomevoicemail(errors[0].field = "outcome").errors[]names the field.422workspace_carrier_failedTwilio did not do what was asked (hold, hand-over); the call's state did not change.502workspace_transfer_recipient_in_acwCC2-R5: a named transfer to a teammate in after-call work is refused until it ends (choose someone else or try again in a moment).409workspace_transfer_not_foundNo transfer of that id is yours to act on.404workspace_transfer_receptionist_busyRefused before the caller moves; the handler keeps them. Try again in a moment.409receptionist_handover_withdrawnInternal (runtime redemption): the team call a re-entry session was minted for no longer hands the caller to the AI (the handler took them back, or the customer hung up). No AI session starts.409handoff_redirect_not_allowedThe credential is valid but may not perform this action here. The problem detail names what is missing.403handoff_redirect_not_configuredThis deployment has no transfer worker or signing key; nothing changed.503workspace_transfer_destination_not_foundPATCH /workspace/transfer-destinations/{id}: no live entry of that id on this company's list.404workspace_transfer_destination_takenThat number is already on the transfer list (errors[0].field = "phone_e164"); rename the existing entry instead.409workspace_parked_call_not_foundThe parked caller was already picked up by someone else, or hung up. Refresh the parked list.404workspace_pickup_not_readyPicking up a parked caller needs a fresh calling check of this person's phone or browser (the server rings that client). Nothing was claimed.409workspace_contact_not_heldCalling this customer is not held, so there is nothing to review.409contact_permission_refusedPOST /v1/workspace/contacts/{id}/permissionnamed a customer who asked not to be contacted. A do-not-contact preference stays in force; recording permission cannot override it.409workspace_voice_callback_refusedNot a verifiable carrier callback for this account (any reason; deliberately indistinguishable).403emergency_notice_not_acceptedPUT …/emergency-lines/{phone_number_id}/addresswithoutaccept_notice: truefor the CURRENT VoIP-911 notice version (notice_versionin the body names the version you must accept, as served byGET …/emergency-lines). Nothing was saved.409emergency_address_invalidThe address cannot be registered for 911: a field fails the 911 database's format rules (errors[]names it - two-letter state, five-digit ZIP, no PO Box, no& @ #; nothing was saved), or Twilio's emergency address check refused it (21628) or suggested a correction (21629, the suggestion indetail). In the carrier case the line is recordedfailedandlinecarries it.422emergency_address_carrier_failedTwilio did not complete the 911 registration (credentials refused, no answer, or it would not link the address to the number). The line is recordedfailedwith the reason (line); save again.502emergency_line_not_foundThat phone number is not an in-service voice number on the company's calling account.404numbers_account_not_readyThe company has no verified BYO Twilio account (or its credentials cannot be read). Connect and verify it in Connections.409numbers_carrier_failedTwilio did not answer or did not complete the step (search, caller-ID call, bill upload, cancellation, trust registration). Nothing was assumed; retry.502numbers_owner_requiredBuying, porting and trust registrations act on the company's Twilio account and bill: owners only.403numbers_search_invalidA number search Twilio would refuse: unknown number type, area code not three digits (or toll-free vs local mismatch),containsnot 2-16 digits/letters/*with two non-wildcards, a state on a toll-free search, or limit outside 1-30 (errors[]names the field).422number_purchase_in_progressAnother purchase of this number is open (startedorunresolved);purchase_idnames it. Check it instead of buying again.409number_purchase_refusedTwilio did not sell the number (no longer available, address required, credentials refused, or unreachable before anything was bought). Nothing was bought;purchaseis the recorded purchase.409number_purchase_not_foundNo purchase of that id in this company.404port_in_invalidThe port-in request cannot be saved: target date fewer than 7 days out, a toll-free number, a number listed twice or already a line, or a bill that is not a PDF/JPEG/PNG of at most 10 MB without a password (errors[]names the field).422port_in_not_foundNo port-in request of that id in this company.404port_in_state_invalidThe request is not at that step (submit needs a draft with the bill and the losing account number; cancel is refused while submitting or cancelling);port_incarries it.409port_in_refusedTwilio refused the port-in request with the reason indetail; the request is back todraft(port_in).422caller_id_not_foundNo verified caller ID of that id in this company (or it was removed).404caller_id_is_a_lineThe number is already one of the company's lines on its Twilio account; choose it as caller ID directly.409caller_id_existsThe number is already a verified caller ID;caller_idcarries it.409voice_trust_invalidThe registration cannot be submitted: a CNAM/branded display name breaking Twilio's rules (≤15 characters, letter first, letters/digits/spaces/periods/commas), a Voice Integrity use case or count missing, lines that are not numbers on the account, CNAM on toll-free only, or a Branded Calling bundle not on the account.422voice_trust_profile_requiredTwilio's Primary Business Profile is not approved; it is created once in the Twilio Console (Trust Hub → Customer Profiles). Nothing was created.409voice_trust_kind_unknownNot a registration Vocapable submits (shaken_stir,cnam,voice_integrity), or none of that kind exists yet to check.404workspace_reply_not_foundNo reply of that id that you can open.404workspace_reply_already_sentThe reply has left (or was attempted); write a new one.409workspace_reply_already_attemptedThe carrier refused it (failed) or we could not confirm it (uncertain, never re-sent automatically).statesays which.409workspace_case_not_foundNo case of that id that you can open.404workspace_case_existsThat conversation already has a case;case_idnames it.409workspace_case_source_invalidThe source named is not one of this customer's conversations.422workspace_case_invalidThe response commitment must be in the future.422workspace_case_state_invalidThe case is not in a state that allows this (reopen before changing a resolved case).statussays where it is.409workspace_thread_assignee_invalidA conversation goes only to an active member of this company who can open it.reason:not_an_active_member(unknown, another company's, suspended or revoked) orcannot_see_conversation(a rep whose relationships do not include this customer). Nothing changed.422workspace_line_not_foundThat line is not an in-service voice number on the company's calling account.404workspace_line_not_permittedYou may not call from that line (it is limited to its members), or a teammate's default cannot be a line they may not use. Nothing was reserved.403workspace_no_line_availableEvery line is limited to members and you are not one; ask an owner or manager.409workspace_owner_requiredOnly the owner changes the company's calling settings.403workspace_personal_calling_disabledThe owner has not allowed calling customers from personal phones. Nothing was recorded.403workspace_callback_phone_missingYou have no verified phone for a carrier callback; verify your mobile number for transfers first. Nothing was reserved.409workspace_dial_pad_disabledThe owner has not allowed dialling numbers that are not in Contacts.403workspace_calling_window_not_narrowerA calling window can only be made stricter: choose one inside the product default (08:00–20:00 in the customer's local time) that opens before it closes. Nothing was saved.422workspace_voicemail_drop_audio_invalidNot a playable drop.errors[0].reason:not_base64,unsupported_format(not WAV, M4A/MP4 or ADTS AAC, or a codec other than AAC/PCM),undecodable(the container or its audio does not decode),too_short(under 1 s of audio),too_long(over 60 s) ortoo_large(over 6 MB). Nothing was stored.422workspace_voicemail_drop_name_requiredGive the recording a name you will recognize on a call.422workspace_voicemail_drop_limitYou already have five drops; delete one first. Nothing was stored.409workspace_voicemail_drop_not_foundNo drop of that id that you can open.404a2p_registration_invalidThe registration form is missing something Twilio requires;fieldsmaps each field to the reason. Nothing was saved.422a2p_registration_stateThe registration is not in a state that allows this (edit only before submitting or after a refusal; submit once; check after submitting; re-send a code only while verifying).stagesays where it is.409text_template_invalidThe template uses a merge field that does not exist;fieldslists them.422text_template_name_takenA saved text already has that name.409workspace_media_invalidThe image cannot be sent or attached.reason:not_base64,empty,unsupported_format(not JPEG/PNG/GIF),corrupt,too_large(over 5 MB, or over 5 MB together),too_many(over 10),not_attachable(not this customer's, not stored, or already on another text).422workspace_media_not_readyThe image is still being fetched from the carrier, or could not be (status).409workspace_text_emptyA text needs words or an image.422workspace_text_schedule_invalidChoose a send time from one minute to 30 days ahead.422workspace_text_not_scheduledOnly a scheduled text can be withdrawn;statesays what it is.409recap_draft_no_customerLink the call to a customer before drafting a recap.409recap_draft_nothing_recordedSave the wrap-up notes or a next step first; the recap is written from them.409
9.18 The integration hub (`/v1/workspace/integrations/*`)
Reading the catalog, installations, activity and conflicts is open to every person in the company (a rep's Connections tab is view-only); every change needs manage_integrations (owner or manager).
integration_provider_unknownThe provider is not one of the 26 catalog tools.404integration_installation_not_foundNo connection of that id in this company.404integration_plan_unreviewedThe setup plan (resource, accountable teammate, data scope) was not reviewed - or a paused connection's plan changed and must be reviewed before resuming (409).422 / 409integration_data_groups_requiredSelect at least one data group.422integration_data_group_unknownA data group is not one this tool lists.422integration_capability_unknownA requested capability is not one of this tool's.422integration_resource_invalidA selected resource is empty or longer than 200 characters.422integration_config_invalidOnly an account address (subdomain, shop, region) may be configured, and it must be a plain host label.422integration_backup_owner_invalidThe backup owner must be someone other than the connection owner.422integration_setup_existsThe company already has an open setup for this tool;installation_idnames it.409integration_transition_refusedThe step is not possible from the connection's current state (status,eventsay which) - e.g. activating before an account call AND an operation were verified.409integration_adapter_not_builtNo adapter for this tool is registered in this release, so no account can be verified; the plan stays a draft.409integration_platform_credentials_missingThe Vocapable app registration with this provider is not configured;missinglists the exact environment variables an operator must set.409integration_auth_mismatchThe tool is connected the other way (authorize an account vs submit a credential).409integration_credential_invalidProvide exactly the credential fields the tool asks for.422integration_provider_errorThe provider did not return what was asked;error_classclassifies it.502integration_recovery_unreviewedReview the recovery (or conflict decision) before completing it.422integration_disconnect_unconfirmedConfirm the disconnect: it stops every sync and delivery for the tool.422integration_conflict_not_foundNo unresolved conflict of that id in this company.404integration_crm_home_invalidThe external CRM home must be HubSpot, Salesforce, Pipedrive or Zoho CRM.422integration_crm_home_needs_planSave a reviewed sync plan for that CRM before choosing it as the home.409integration_redirect_not_configuredVOCAPABLE_INTEGRATION_OAUTH_REDIRECT_URI(orVOCAPABLE_PUBLIC_API_BASE_URL) is not set.503webhook_destination_plan_requiredSave a reviewed Webhooks setup plan (owner and data) before adding a destination.409webhook_destination_url_invalidIn production every DNS answer is checked at save time; the transport re-resolves and pins a vetted public address at send time and never follows redirects.422webhook_destination_events_invalidChoose at least one workspace event type (customer.updated,call.completed,transfer.result,followup.changed,deal.updated,handoff.created,handoff.completed).422webhook_destination_not_foundNo destination of that id in this company (or it was removed).404webhook_destination_unverifiedDelivery turns on only after a signed test to the destination's current URL answered 2xx.409webhook_delivery_not_redeliverableOnly an exhausted delivery of this destination can be put back on the ladder; a delivered or still-retrying one cannot.409automation_key_unboundThe key is not the company key of a Zapier or Make connection (or that connection was disconnected). Mint it in Connections.403automation_owner_inactiveThe connection's accountable owner is no longer an active member; assign a new owner in Connections.403automation_not_activeActions run only after a person reviewed and activated the private integration in Connections.409automation_pausedThe private integration is paused; nothing is delivered or run until a person resumes it.409workflow_recipe_unknownNot one of the four workflow starters.404workflow_plan_unreviewedChoose a responsible teammate and confirm you reviewed the owner, reminder and stop conditions.422workflow_plan_not_foundNo workflow plan of that id in this company.404workflow_approval_staleThe plan changed since it was reviewed (its digest differs, or it is not the reviewed version); review the current version and activate it.current_digestnames it.409workflow_not_runningThe workflow is not active (or not paused, for resume).409workflow_run_not_foundNo workflow run of that id that you can open (a rep opens the runs they own).404workflow_run_finishedThe run already completed, was cancelled, or failed.409approval_reviewer_ineligibleThe teammate you chose cannot review this request: they are not an active owner or manager holding the permission it needs, or they asked for it.422workspace_teammate_not_foundNobody with that id works in this company (or they no longer do).404workspace_member_existsSomeone in this company already uses that email address; nothing was sent.409workspace_invitation_existsAn invitation for that email (compared case-insensitively) is already pending in this company.invitation_idnames it; resend it instead.409workspace_invitation_not_foundNo pending invitation with that id belongs to this company.404workspace_invitation_delivery_failedThe invitation email could not be handed to the email provider; the invitation was rolled back and no link works. Try again.503workspace_invitation_unusableThe invitation cannot be accepted:reasonisinvalid(revoked, replaced or already used),expired,email_mismatch(sign in with the invited address),already_memberorrep_linked.409workspace_self_change_refusedNobody changes their own role or offboards themself; ask another owner or manager.409workspace_membership_requiredThe company's founding owner holds the account's original owner access, which a teammate cannot change or offboard here.409workspace_owner_change_refusedOnly an owner can make someone an owner or change another owner.403workspace_offboard_target_invalidThe teammate chosen to take over is not an active person of this company other than the one leaving.422workspace_routing_plan_not_foundThere is no routing draft (or no plan with that id) in this company.404workspace_routing_member_invalidA routing group may contain only active teammates; invited people join once they accept.422workspace_routing_number_not_foundThe number is not an active voice number of this company.404workspace_routing_strategy_not_liveLongest available cannot be published: the phone line can ring people in order or together, but has no live availability tracking. Choose Owner first or Ring together.409workspace_routing_no_eligible_membersNobody in the routing group has a verified transfer phone, so the phone line could ring nobody.excluded[]lists each person and why.409workspace_routing_ai_agent_requiredThe fallback or after-hours step is the AI receptionist, but the number has none; connect one or choose callback/voicemail.409workspace_routing_policy_invalidThe routing could not be expressed as a valid answering policy for this number.422workspace_routing_not_liveA phone test checks live routing; this plan is not live.409workspace_routing_test_call_not_foundNo real inbound call has reached the number since routing went live (no teammate call leg, AI-answered call or recorded voicemail). Call the number from another phone and check again.409workspace_routing_superseded_by_call_flowThe number has a published call flow; publishing routing would overwrite its answering policy. Edit the line's call flow instead.409call_flow_line_not_foundThe line is not an active voice number of this company.404call_flow_invalidThe flow cannot be written as a valid answering policy for this number (detailnames the first reason), or a stored draft no longer validates; save it again.422call_flow_not_publishableThe draft has references or combinations that cannot run.409call_flow_version_not_foundRollback names a revision this line never published.404call_flow_test_unpublished"Call me as a caller would" plays the live flow; publish it first.409call_flow_test_number_unverifiedTest calls ring only a number the company verified with a code.422call_flow_test_limitThe company placed ten flow test calls in the last 24 hours.429call_handoff_brief_not_foundNo AI-to-human handoff with a brief by that id that you may open (owners and managers read any; a representative only their own).404workspace_recording_not_offeredPOST /workspace/calls/{id}/recordingwithstarton a call whose line does not record, a personal-phone attempt ("Not recorded - made from a personal phone"), a company whose recording staff turned off, or a call whose caller already declined. Nothing was recorded.409workspace_recording_state_invalidThe recording is not in a state that allows the action (statenames it): already started, not running, not paused, already stopped, or the call ended.409workspace_recording_not_foundThe call has no recording, or it is not one you can open: a recording is open to the conversation's handlers, managers and owners only.404workspace_recording_disabled_by_staffVocapable staff turned human-call recording off for the company (recording.controls.set); onlymode: offcan be saved until that is reviewed.409workspace_recording_announcement_invalidThe announcement must be 20–240 characters and say the call is recorded AND transcribed by AI.422workspace_recording_retention_invalidRecordings are kept 7–365 days; longer needs a staff review that raises the company's ceiling.422workspace_recording_notice_requiredTurning recording on - or changing what callers hear or the retention - needsaccept_notice_versionequal to the current notice (notice_versionand the exactnoticetext are in the problem).422workspace_recording_hold_reason_requiredA litigation hold needs a reason (the matter or request it preserves).422workspace_voicemail_not_foundNo voicemail with that id that you can open.404workspace_voicemail_assignee_invalidA voicemail can be assigned only to an active teammate.422workspace_voicemail_cursor_invalidThe page cursor is not one this list issued; reload from the first page.422workspace_coaching_not_foundNo coaching item with that id that you can open. A rep opens their own; a draft is its author's until shared.404workspace_coaching_action_invalidThat step does not apply to this item now, or it is someone else's to take (only the teammate acknowledges, disputes or corrects; only the author shares).409workspace_coaching_subject_invalidCoaching is for an active person of this company.422workspace_coaching_call_invalidThe cited call is not one the coached person handled (or, for a rep, not their own).422workspace_coaching_scenario_invalidPractice must name a published answer (collection, version and answer) from this company's approved knowledge.422workspace_knowledge_not_publishedThe knowledge collection has no approved version yet.409workspace_knowledge_review_not_foundNo knowledge review with that id belongs to this company.404workspace_knowledge_review_closedThe review was already published, dismissed or rolled back.409workspace_knowledge_version_movedA newer knowledge version was published after this was raised; nothing changed.current_versionsays which is current - check again against it.409workspace_knowledge_source_invalidThe answer named is not in the current version, or the text to publish is empty.422workspace_knowledge_no_website_sourceNo approved answer in the collection came from a website, so there is nothing to compare.409workspace_knowledge_rollback_invalidRollback needs an earlier, approved version of this collection.422integration_backup_owner_requiredThis tool's connection is owned by a person at the provider (a Microsoft Teams Workflows flow): name a backup owner, and it cannot be cleared.422workspace_report_email_failedThe email provider did not accept the report email; nothing was sent. Try again.503workspace_screening_rule_not_foundThat blocked or allowed number was already removed.404workspace_screened_call_not_foundfrom_decision_idnames no screened call of this company.404workspace_screened_caller_withheldThe screened call had no caller ID, so there is no number to block or allow.422phone_retention_out_of_boundsA retention period is outside the range staff set for this company;errors[]names each field and its range.422workspace_supervision_offThe owner has not turned on listening to live calls.409workspace_supervision_not_disclosedThe caller was not told this call may be monitored;reason:policy_unavailable,not_announced,monitoring_not_named,announcement_not_playedorconsent_refused. The refusal is audited.409workspace_supervision_busySomeone already supervises this call, or you already supervise another call.409workspace_supervision_not_foundNo such supervision in this company, or it is not yours.404workspace_supervision_endedThe supervision (or the call) already ended.409
9.19 Business mail and messaging
Email replies leave through the company's own Gmail or Outlook connection: POST /v1/workspace/inbox/threads/{contact_id}/email-replies saves one for review (an approval pins the exact recipient, mailbox, subject and body), the shared /inbox/replies/{id}/review route approves it, and /inbox/replies/{id}/send spends the approval once and queues ONE provider send (operation key = the reply's send key).
workspace_mailbox_privateThat mailbox is private to the person who connected it; only they may send from it until they share it with the team.403workspace_email_recipient_invalidA reply goes only to an email address recorded for this customer (their email or an email contact point).422workspace_mail_message_not_foundThe synced message does not exist, is not this customer's, or comes from a mailbox you may not see.404workspace_mailbox_filter_invalidA label filter is one Gmail label id; Outlook syncs the Inbox. A filter is never an access boundary.422workspace_reply_channel_mismatchAn email reply is edited throughPATCH /v1/workspace/inbox/email-replies/{id}, not the text-reply route.409integration_not_a_mailboxMailbox settings apply to Gmail and Outlook connections only.409integration_not_a_notifierNotification settings apply to Slack and Microsoft Teams connections only.409
9.20 Meetings and appointments (`/v1/workspace/meetings*`, `/v1/workspace/agenda`)
A meeting is the company's commitment to one of its customers at a time, with a responsible host. Reading is scoped like customers (a rep sees meetings they host and those on relationships they may open); a rep hosts only themself.
meeting_not_foundNo meeting of that id in this company, or not one you can open.404meeting_host_not_permittedA rep can host only their own meetings; a manager books for a teammate.403meeting_host_not_eligibleThe host is not an active person of this company.422meeting_time_invalidThe start is not a valid future time (or is more than twelve months ahead).422meeting_duration_invalidChoose 15, 30, 45 or 60 minutes - or the event type's own length.422meeting_purpose_requiredDescribe the purpose of the meeting.422meeting_timezone_invalidThe scheduling or customer time zone is not an IANA zone.422meeting_hours_invalidWorking hours must be weekday ranges ofHH:MMthat end after they start.422meeting_outside_working_hoursThe time falls outside the host's working hours.422meeting_host_overlapThe host already has a workspace meeting (draft or booked) then;conflictslists it.409meeting_slot_conflictThe provider shows the host busy at commit time (it was free at preview); nothing was booked or overwritten;conflictslists the busy ranges.409meeting_calendar_not_connectedThe host has no connected calendar that can write: the meeting stays a draft;calendar_stateandconnect_pathsay what to fix.409meeting_state_invalidThe meeting's status does not allow that now (statussays which).409meeting_outcome_too_earlyAttendance can be marked only after the start time.409meeting_event_type_invalidA Calendly event type is offered only for the person who connected Calendly, and must be readable.409 / 422meeting_plan_requiredThe connected Calendly account's plan does not include the Scheduling API (requirement_code:calendly_paid_plan).409meeting_host_change_requires_replacementA booked meeting keeps its host; book a replacement (replaces_id), which cancels the original once confirmed.409
9.21 CRM sync and Apollo lead intake (`/v1/workspace/integrations/crm/*`, `/apollo/*`)
A CRM's sync plan (direction, field groups with the email match locked on, who wins owner and stage conflicts, stage mapping), its health, its conflicts and the deal changes and call logs waiting for review are readable by everyone in the company; every change needs manage_integrations. Apollo search and enrichment need bulk_import, and spending credits needs a confirmation of the exact estimate.
crm_provider_unsupportedCRM sync exists for HubSpot, Salesforce, Pipedrive and Zoho CRM only.404crm_plan_unreviewedKeep the email match field and review the sync rules (direction, fields, conflict owner) before saving.422crm_plan_invalidA stage mapping is empty; map each chosen stage or leave it out.422crm_sync_not_activeThe CRM connection is not active (authorized, checked and activated);statussays where it is.409crm_review_not_foundNothing waits for review under that id (already decided, or not this connection's).404crm_outbound_not_allowedThe plan's direction is CRM → Vocapable; it does not send records.409crm_record_already_linkedThat record already syncs with its CRM record.409crm_record_not_foundNo such customer, person or deal in this company.404apollo_not_activeApollo is not connected and active for this company (statusnames the state).409apollo_search_emptyAdd at least one title, location, domain, size or keyword.422apollo_run_not_foundNo such Apollo enrichment in this company.404apollo_run_state_invalidThe run cannot do that from its state (status): only an unconfirmed estimate can be confirmed or cancelled.409apollo_run_unreviewedConfirm that the credits may be spent and that new contacts stay on hold.422apollo_estimate_expiredThe 15-minute estimate expired; estimate again.409apollo_estimate_changedThe estimate confirmed is not the current one;estimated_creditsis.409apollo_credits_insufficientApollo reported fewer credits than the estimate needs.409business_connection_not_readyThe chosen connection cannot take this yet;blockersnames why (connection_not_active,capability_not_active,mapping_incomplete,currency_not_supported,template_not_selected,location_not_selected,not_authorized).409business_connection_wrong_kindThe connection is not one of the tools that do this.422business_provider_rate_limitedThe provider asked us to slow down; nothing changed;retry_afterwhen known.429business_provider_errorA request-path provider read failed;error_classclassifies it.502business_review_requiredConfirm you reviewed exactly what goes to the provider (reviewed: true).422business_retry_not_neededThe provider write behind the record has not failed; nothing to retry.409business_mapping_invalidThe ledger mapping names an item/account or tax code the ledger does not list.422accounting_quote_not_acceptedAn invoice reference needs a live acceptance of the quote's current version.409accounting_customer_choice_invalidChoose one matched ledger customer or create one, not both.422accounting_customer_mismatchThe relationship is already matched to another ledger customer (external_id).409accounting_invoice_not_foundNo invoice reference of that id you can open.404accounting_invoice_not_createdThe ledger has not confirmed the invoice yet.409signature_quote_not_readyThe quote has no version, is voided, or its pricing still awaits approval.409signature_recipient_missingThe quote's recipient has no email.409signature_request_existsThe version already has a live signature request.409signature_request_not_foundNo signature request of that id you can open.404signature_request_stateAlready sent or closed (status).409signature_version_changedThe quote changed since the request was prepared; prepare a new one.409signature_not_sentThe provider has not confirmed the document yet.409signature_refresh_too_soonDocusign allows one status read per envelope every 15 minutes (next_refresh_at).429service_handoff_not_acceptedOnly an accepted, still-open delivery handoff is handed to field service.409service_address_requiredChoose the client's service address or enter one (ServiceTitan always needs one).422service_client_mismatchThe relationship is already matched to another client there (external_id).409service_job_not_foundNo service request of that id you can open.404service_job_not_createdThe provider has not confirmed the request yet.409support_conversation_requiredAn Intercom case links the customer's existing conversation (found by their email).422support_link_not_foundNo help-desk link of that id you can open.404support_link_not_createdThe help desk has not confirmed the link yet.409status_updates_not_neededThis tool's events are signed with the platform app secret, or it is polled.409status_updates_key_requiredDocusign: paste the account's Connect HMAC key (sealed, never shown again).422status_updates_unsignedThe provider issued no signing secret; unsigned updates are never accepted.502merchant_obligations_openThe current merchant still has open payment pages; switch after they settle or close.409
9.22 Contact center (`/v1/workspace/contact-center/*`, `/v1/workspace/me/agent-state*`, `/v1/workspace/quality/*`, teams/roles/SSO/SCIM)
One section for the contact-center layer.
contact_center_not_enabledThe contact center (or, for queue routing, itscontact_center_routingsub-switch) is not turned on for this company - a staff-set entitlement, off by default in production. Lines keep ringing their teams as today; Available / Not ready / Offline with the built-in reasons work regardless. Nothing changed.403cc_queue_not_foundNo live queue of that id in this company, or a policy names a queue that was archived.404cc_queue_name_takenAnother live queue already has this name (compared case-insensitively).409cc_queue_limitThe company already has 200 queues; archive one first.409cc_queue_in_useA published call flow, or another queue's overflow/steps, still routes into this queue; change that first.409cc_queue_overflow_selfA queue's overflow or a step's overflow queues name the queue itself.422cc_queue_overflow_cycleCC1-R1: the queue's overflow and its steps' overflow queues would close a circle (A → B → A);cyclenames the queues.422cc_queue_member_not_foundA member (or the person whose skills are edited) is not an active person in this company.422cc_skill_not_foundA requirement or a skill set names a skill that is not a live skill of this company.422cc_skill_name_takenAnother live skill already has this name.409cc_skill_limitThe company already has 500 skills; retire one first.409cc_skill_in_useA queue's steps or VIP rules require this skill; remove it there first.409cc_requirement_invalidA skill requirement written as text cannot be routed: an unknown skill, a level outside 1–5, a syntax or bracket error, more than 20 terms, more than 10 alternatives, a skill named twice at one level, or an OR nested too deep.reason,position(0-based) andtermname the failing term.422cc_contact_not_foundThe simulator's customer is not one of this company's live contacts.404cc_routing_change_refusedA routing configuration write was refused for a reason not listed above; reload and retry.409cc_routing_trace_not_foundThe call did not reach the team through a contact-center queue, so it has no routing trace.404agent_reason_not_applicableOnly Not ready takes a reason. Nothing changed.422agent_reason_code_unknownThat reason is neither built in nor an active company reason. Nothing changed.422agent_next_state_not_applicableA next status is chosen during a call or its after-call work; otherwise change the state directly.409agent_acw_not_activeThere is no after-call work running to extend or end.409agent_acw_extension_limitAfter-call work was already extended as many times as the company allows.409agent_auto_answer_not_allowedThe company has not allowed auto-answer; an owner or manager turns it on first.409agent_reason_code_existsA reason with that name already exists (including the built-ins). Nothing was created.409agent_reason_code_limitA company can have at most 50 active reasons of its own.409cc_state_transition_invalidCC2-R1: the agent state transition table does not list this change (e.g. declaring a state while on a call - choose a next status; a supervisor signing out an agent on a call is refused until the call ends, CC3-R5; ringing → not ready). The detail names the states.409agent_reason_code_not_foundNo company reason with that id.404agent_history_window_invalidsincemust be beforeuntil, at most 31 days apart.422cc_caller_not_foundNo waiting caller of that id in this company.404cc_caller_not_waitingThe caller was answered, left, or took a callback; nothing was changed.409cc_caller_not_queue_routedThe caller is on a line that rings its team without queues; such callers cannot be moved or reprioritized.409cc_caller_same_queueThe caller is already in that queue.409cc_alert_rule_not_foundNo live alert rule of that id you can see or edit.404cc_alert_rule_limitThe company already has 200 alert rules; archive one first.409cc_alert_rule_invalidA service-level or abandon-rate threshold is a fraction between 0 and 1.422cc_alert_not_foundNo fired alert of that id you can see.404cc_alert_preferences_invalidThe time zone is not an IANA zone.422cc_wallboard_view_not_foundNo live wallboard view of that id that is yours (or, for reading, shared with you).404cc_display_token_invalidThe display token is missing, unknown or revoked. Create a new display from the wallboard.401cc_dialer_not_enabledThe outbound dialer is not switched on for this company.403cc_dialer_mode_not_enabledPower or predictive dialing is not enabled for this company (preview and progressive remain).403cc_dialer_owner_requiredOnly an owner may switch a campaign to progressive, power or predictive, or turn on (or change) the preview timer.403cc_dialer_preview_timer_invalidAtrigger: timerdial on a campaign without a preview timer, or before the session'sauto_dial_at.409cc_dialer_voicemail_drop_not_foundThe campaign names a voicemail drop that is not one of the company's.422cc_dialer_acknowledgement_requiredA paced mode needs the owner's acknowledgement of the current text (acknowledgement_versionin the extensions).422cc_dialer_campaign_not_foundNot one of this company's campaigns you can see.404cc_dialer_list_not_foundNot one of this campaign's live lists.404cc_dialer_lead_not_foundThe lead is not the one your session is working.404cc_dialer_session_not_foundYou have no open dialer session (or it is not yours).404cc_dialer_name_takenAnother live campaign has this name.409cc_dialer_abandon_message_invalidThe abandon message must name the seller, say one of your own numbers as the callback number, and offer "press N" to opt out.422cc_dialer_campaign_state_invalidThe campaign's status does not allow this action.409cc_dialer_governor_pausedThe campaign paused at 3% abandoned over 30 days and cannot resume until the rate is below 2.5%.409cc_dialer_list_invalidThe CSV cannot be read (size, header, rows).422cc_dialer_dispositions_invalidThe disposition set is invalid (keys, labels, retries; DNC never retries).422cc_dialer_number_not_ownedA caller ID or callback number is not one of the company's own active numbers.422cc_dialer_already_seatedYou already have an open session in a campaign.409cc_dialer_disposition_requiredSave the last call's disposition before the next lead (or leaving).409cc_dialer_disposition_unknownNot one of this campaign's dispositions.422cc_dialer_dial_heldThe dial gate held this lead now;holdsnames why.409cc_dialer_not_previewThis campaign dials for you (or this action is for server-dialed calls only).409cc_dialer_ring_too_shortRing time is at least 15 seconds (47 CFR 64.1200(a)(6)).422cc_dialer_change_refusedThe change was refused; reload and retry.409cc_dialer_duplicateAlready created under this idempotency key.409cc_dialer_call_movingThe call is still moving to its own room (or has not been moved yet:POST /sessions/{id}/call-roomfirst); the caller stays with you.409cc_dialer_transfer_heldThat allow-listed number cannot be rung now;holdsnames why (do_not_contact,outside_local_window,timezone_unknown,spend_cap_reached) andwindow_opens_atwhen it opens.409cc_quality_not_enabledThe owner has not turned quality management on in its settings.409cc_quality_owner_requiredOnly the owner changes quality settings.403cc_ai_policy_not_acceptedTurning AI scoring on requires accepting the current AI QA policy statement (current_version).422cc_ai_policy_outdatedThe accepted policy version is not the current one; read and acceptcurrent_version.409cc_scorecard_invalidThe scorecard definition broke a rule (errors[].field): weights 1-100, at most 100 questions, auto-fail only on yes/no questions, unique keys.422cc_scorecard_name_takenAn active scorecard already has that name.409cc_quality_not_foundNo such scorecard, evaluation, dispute, call, text conversation or calibration session you can open (a blind calibration answer, too).404cc_quality_call_not_evaluableThe call is still live, not completed, or has neither a recording nor a transcript; a text conversation is still open, nobody handled it, or it has no messages; calibration sessions take calls only.409cc_quality_own_callNobody evaluates a call they handled.409cc_quality_evaluation_existsYou already have a draft (or a calibration evaluation) of this call;evaluation_idnames it.409cc_quality_answer_invalidAn answer does not fit its question (N/A where not allowed, a scale value on yes/no, an unknown question).422cc_quality_answers_incompleteAnswer every question (N/A where allowed) before sharing;errorslists the unanswered keys.422cc_quality_state_invalidThat step does not apply to the evaluation, dispute or session now, or it is someone else's to take.409cc_quality_dispute_window_closedAnswers can be disputed within 14 days of the evaluation being shared.409cc_quality_dispute_existsThat answer already has an open dispute.409cc_quality_second_reviewer_requiredA dispute is resolved by someone other than the evaluator and the agent who raised it.403cc_quality_reviewer_invalidEvery calibration reviewer must be an active person in this company.422cc_quality_report_window_invalidA report window runs forward and spans at most 366 days.422cc_wfm_shift_not_foundNo live shift of that id you plan for (or, for a swap, that is yours and published).404cc_wfm_template_not_foundNo live shift template of that id.404cc_wfm_request_not_foundNo time-off or swap request of that id that you made, were asked to answer, or may decide.404cc_wfm_exception_day_not_foundNo live exception day of that id.404cc_wfm_person_not_foundThat person is not an active member of this company, or is outside the teams you plan for.404cc_wfm_schedule_invalidThe shift or template breaks a rule (the detail says which): quarter-hour grain, 30 minutes to 16 hours, activities inside the shift and not overlapping, a custom activity names one of the company's reason codes, template names are unique.422cc_wfm_shift_overlapThat person already has a shift overlapping this one.409cc_wfm_request_closedThe request is no longer pending, or (a swap) the colleague has not answered yet.409cc_wfm_swap_unqualifiedThe colleague does not serve all of your queues, or a shift in the swap is not theirs / has started.422cc_wfm_range_invalidDates out of range: time off in the past or longer than 31 days, too many days asked for, an override off the 15-minute grain, a future day's intraday or adherence.422workspace_team_scope_refusedYour role sees only the teams you lead, and this view covers the whole company (the line-level phone report, owner alerts, platform usage and retention).capabilitynames the permission. Open your team's board orGET /workspace/teams/{id}/reportinstead.403workspace_team_not_foundNo live team of that id in this company - or, for a team-scoped role, not a team you lead.404workspace_department_not_foundNo live department of that id in this company.404workspace_team_member_invalidTeams hold memberships of this company that are not revoked;membership_idis not one.422workspace_team_managed_by_idpThe team mirrors an identity-provider group (SCIM); change its name and members there.409workspace_team_tree_invalidThe change would break the team tree.reason:cycle(under itself or one of its own teams),too_deep(more than five levels),department_node(a department's node is renamed or archived as the department).409audit_export_range_too_longAn audit export covers at most 13 months (max_months); narrowsince/untiland export each range.422audit_entry_not_foundGET /mobile/workspace/audit-log/{entry_id}: no entry of that id in this company's audit trail (another company's id reads the same).404scim_group_mapping_invalidThe group mapping cannot be saved.reason:not_a_scim_group(the team does not mirror an IdP group),target_not_found,duplicate,target_incomplete(a queue mapping names a queue; a skill mapping a skill and a proficiency 1-5).422sso_logout_invalidGET/POST /auth/sso/saml/{connection_id}/slo: the LogoutRequest is unsigned, its signature does not verify with the IdP certificate, or its Issuer, Destination or validity window is wrong (reason). Nothing was ended.400workspace_name_takenA live team, department or custom role already has that name (ignoring case); custom roles also cannot be named Owner, Admin, Manager or Rep.409workspace_role_invalidThe capabilities or permissions are not allowed for a custom role.422workspace_role_not_foundNo live custom role of that id in this company.404workspace_role_in_usePeople still hold the role (holders); give them another role before archiving it.409workspace_role_owner_refusedOwners keep the owner role; a custom role cannot be given to an owner.409workspace_membership_not_foundNo active member of that id in this company.404workspace_import_file_invalidThe CSV cannot be imported.reason:file_too_large(1 MB),too_many_rows(2,000),headers_invalid(first row must nameemailplus any ofname,role,team,teams,skills,status,queue,queues),empty_file,not_utf8,csv_malformed. Row-level problems are not errors: the preview marks each row.422workspace_import_not_foundNo people import of that id in this company.404workspace_import_file_changedApply names the SHA-256 of the previewed file and this is not it. Preview the new file first.409workspace_import_expiredA preview can be applied within a day of being made. Upload the file again.409workspace_bulk_edit_invalidThe bulk action needs another field (roleforset_role,team_idfor team actions,queue_idfor queue actions,skillsorremove_skill_idsforset_skills);errors[]names it.422sso_configuration_invalidThe SSO settings cannot be saved.422sso_domain_not_foundNo claimed domain of that id in this company.404sso_domain_claimedAnother company already verified this domain; a domain belongs to one company.409sso_not_configuredPOST /auth/sso/start: single sign-on is not set up for this email's domain (no verified domain, or the connection is off). The same answer for every reason, so domains cannot be enumerated.404sso_provider_unreachableThe company's identity provider's discovery document could not be read. Try again; the administrator should check the issuer.502sso_ticket_invalidPOST /auth/sso/complete: the one-use ticket is unknown, spent, older than two minutes, or presented without the browser binding that started the sign-in. Start again.401sso_requiredThe company enforces single sign-on and this browser session did not come through its identity provider (company_idnames it). Sign in with SSO; only the named break-glass owner keeps password sign-in. Raised byPOST /auth/console-keyandGET /mobile/authorize.403cc_integrations_owner_requiredOnly the owner changes the contact-center integration settings.403cc_pci_call_not_liveThe call is not in progress; a payment pause applies to a live call.409cc_pci_not_pausedNothing to resume: the pause already ended (by a person, by itself, or with the call).409cc_assist_suggestion_not_foundNo such suggestion on your panel for this call.404cc_assist_window_invalidA usage window runs forward and spans at most 366 days.422cc_cti_not_connectedThat tool is not connected with a verified click-to-dial capability.409cc_cti_contact_unknownThe clicked number is not a customer in Vocapable (consent and do-not-call need the record); add them first.409cc_cti_number_invalidThe clicked number is not one Vocapable can call.422cc_messaging_not_enabledRouting texts through queues (contact_center_messaging, with queue routing and the master) is not on for this company. Texts land in the team inbox as today. Nothing changed.403cc_conversation_not_foundNot one of this company's routed conversations, or not one you may open or act on (only its holder, or a supervisor who may reassign, closes or transfers it).404cc_conversation_offer_goneThe offer timed out, was already answered, or moved to someone else. Nothing changed.409cc_conversation_closedThe conversation is closed; a new text from the customer opens a new one.409cc_conversation_agent_at_capacityThe teammate already holds as many conversations as their capacity allows. Nothing changed.409cc_conversation_contact_existsThe texter already has a contact; open the inbox thread.409cc_conversation_change_refusedA conversation write was refused for a reason not listed above; reload and retry.409cc_messaging_line_not_foundThe line is not one of this company's shared-phone lines.404cc_report_invalidThe definition asks for an unknown or real-time-only metric, an unknown dimension (or a CRM field that is not reportable), more than 12 fields, a range over 400 days, or sub-day intervals over more than 31 days.422cc_report_too_largeA skill, campaign or CRM-field report (counted from the contacts) is over a limit;limitsays which:days(> 92),contacts(> 100,000 in a period),rows(> 5,000) ortimeout(> 20 s). Nothing partial is returned.422cc_saved_report_not_foundNo live saved report of that id that is yours (or shared with you, for reading and scheduling).404cc_report_schedule_not_foundNo live report schedule of that id that is yours.404cc_report_recipient_refusedA recipient is not an active teammate holding team metrics over at least this report's scope (user_idslists them).422
9.23 Existing company agent setup
business_knowledge_changedShared company/location answers, their selected revisions or the original request changed. Refresh and review the current answers before sharing or compiling.409company_setup_company_mismatchThe selection names another company, an acquisition application, multiple companies or a different SSO company scope.403company_setup_not_foundNo workspace/agent in the authorized company matches.404company_setup_request_conflictAn original adoption key was reused with a different body or actor.409company_setup_subscription_requiredCreation needs the actual current active paying subscription; a sandbox, expired, comped or delinquent company does not qualify.409company_setup_product_not_purchasedThe company has not purchased the selected product/capacity.409company_setup_agent_not_editableThe existing agent is not a supported editable product/status.409company_setup_agent_changedThe expected source-agent timestamp changed. Read/review the actual source before proceeding.409company_setup_phone_review_requiredLinked number inventory exceeds the bounded checkpoint or has an unsupported ownership mode.409company_setup_revision_changedAnother save advanced the workspace. Read saved progress before correcting/retrying.409company_setup_product_mismatchReceptionist coverage or a calling task was supplied for the wrong product.409company_setup_edit_requiredOpen the original company draft before compiling or discarding it.409company_setup_edit_already_openFinish the existing company or purchase-origin draft before opening another editor.409company_setup_source_changedThe original draft, agent status, published pointer or release state changed. Undo must not overwrite other work; explicit keep-current recovery remains available.409company_setup_test_in_progressA real release candidate or qualification job is in progress; draft writes and undo wait for it to finish or be withdrawn.409company_setup_voice_requiredSelect an available stock voice or retain the actual owned approved custom voice before advancing.409company_setup_approval_requiredRecovery requires the original company-bound test, not a legacy or purchase-origin test.409company_setup_approval_changedThe original owner, reviewed draft, workspace revision or staged candidate no longer matches the saved test approval.409company_setup_phone_changedThe owned phone route or saved call-plan fingerprint changed after approval. Recover through support before replacing that test.409company_setup_no_changesThe reviewed draft has no changes to apply to the serving receptionist.409qualification_worker_activeA worker lease remains attached to this test. Expiry alone does not prove that a carrier call stopped.409qualification_not_pausedOnly a paused or failed test can return to editing; running, completed and cancelled tests cannot be cancelled again.409qualification_probe_unresolvedThe original physical call or recording cleanup must be reconciled before editing can resume.409
This index lists the codes an API key can receive. Codes raised only on the staff console or on internal runtime surfaces keep their own pages so every typeURI resolves, but are not listed here. The index and every code page are regenerated from the registry of record on each build; the build fails if they diverge.