Error reference

Every error code the API can return, what triggers it, and how to recover.

account.suspendedReturned on any state-mutating request when the workspace status is suspended. No operations are permitted until an admin reinstates the workspace.accounts.admin_requiredReturned when an endpoint requires at least the admin workspace role but the authenticated member has a lesser role such as member or viewer.accounts.last_ownerReturned when a demotion or removal would eliminate the last workspace owner. Promote another member to owner first before proceeding.accounts.remove_deniedReturned when a removal is attempted without sufficient role authority. Self-removal is allowed for any non-sole-owner. Removing others requires owner or admin role.accounts.role_change_deniedReturned when a role change is attempted by someone who is not an owner or admin, or when a non-owner tries to mint another owner.accounts.write_deniedReturned when a viewer or read-only member attempts a state-mutating request. Applies across numbers, wallet, webhooks, API keys, storage, and memberships.api_key.already_revokedReturned when a revoke request targets a key that is already in revoked state. No action is taken; the key remains revoked.api_key.expiredReturned when the API key JWT has passed its expiry timestamp. Revoke the expired key and mint a new one with an appropriate expiry.api_key.invalidReturned when the API key JWT is structurally invalid or fails cryptographic verification. The key cannot be used; mint a new one if the original is lost.api_key.name_requiredReturned when a key creation request omits the label field. Provide a non-empty label to identify the key and resubmit.api_key.not_foundReturned when an API key management operation targets an ID that does not exist or belongs to a different workspace. Verify the key ID.api_key.revokedReturned when the API key was explicitly revoked via the key management UI or API. The key cannot be used regardless of its expiry. Mint a new key.api_key.scope_deniedReturned when the API key is valid but lacks the specific scope the route requires. Mint a new key with the needed scope or use a broader-scope key.api_key.scope_invalidReturned at key mint time when a scope string is not recognized by the platform. Use only scopes from the documented scope list.audit.invalid_action_kindReturned when an audit log filter uses an action_kind value that is not recognised. Use one of the documented values.auth.admin_requiredReturned on admin-only routes when the request lacks the required admin session marker. End-user sessions cannot access admin routes.auth.cannot_unlink_only_authReturned when unlinking Google OAuth would leave the account with no sign-in method. Add another authentication method before unlinking.auth.email_takenReturned when a signup is attempted with an email that is already registered. Direct the user to sign in or use a different email address.auth.google_exchange_failedReturned when the server-side call to Google's token endpoint fails. This is a transient upstream error; retry the sign-in flow after a short delay.auth.google_not_configuredReturned when Google sign-in is attempted while it is unavailable. Use the email sign-in link instead.auth.google_state_mismatchReturned when the Google OAuth callback state cookie is absent or tampered with. This is a CSRF protection check; restart the sign-in flow to get a fresh state.auth.invite_email_mismatchReturned when accepting an invite with a session whose email differs from the invite target. Sign in with the invited email address to accept.auth.no_workspaceReturned when a signed-in user attempts to access a workspace route but has not yet completed onboarding. Redirect to the workspace creation flow.auth.session_invalidReturned on any authenticated route when no valid session is present. The client should redirect to the sign-in page to obtain a fresh session.auth.token_expiredReturned when a magic-link token is presented after its 15-minute validity window. The user must request a fresh link to sign in.auth.token_invalidReturned when a magic-link token does not pass HMAC verification or has a malformed structure. Do not retry; request a new link.auth.token_usedReturned when a single-use magic-link token is presented after it was already redeemed. The user must request a new link to sign in again.auth.workspace_forbiddenReturned when the authenticated identity attempts to access a workspace it is not a member of. Ensure the correct workspace ID is being used.calls.events_failedReturned when GET /v1/calls/{id}/events encounters an internal failure. Retryable with exponential backoff per the 5xx policy.calls.get_failedReturned when GET /v1/calls/{id} encounters an internal failure. Retryable with exponential backoff per the 5xx policy.calls.list_failedReturned when GET /v1/calls encounters an internal failure. Retryable with exponential backoff per the 5xx policy.calls.not_foundReturned when a call lookup, events, or recording request targets an ID that does not exist or is cross-workspace. Verify the call ID and workspace context.calls.recording_expiredReturned when a recording existed but was deleted after its retention period. Choose a larger storage size, or download recordings before they expire.calls.recording_failedReturned when a recording download link could not be created. Retry with exponential backoff.calls.recording_not_foundReturned when a recording is requested for a call that was not recorded. Check that recording was switched on for the call.calls.stats_failedReturned when GET /v1/calls/stats fails because of a server error. Retry with exponential backoff.currency.unsupportedReturned when a request specifies a currency not supported by the platform. Use one of KES, UGX, TZS, RWF, ZAR, GHS, or NGN.idempotency.conflictReturned when the same Idempotency-Key is sent with a different body than the original request. Resend the original body or use a new key.internal_errorReturned when an unhandled internal error occurs and no more specific code applies. Retryable with exponential backoff per the 5xx policy.invitations.not_foundReturned when an invite accept or lookup targets an invitation ID that does not exist or was previously revoked by a workspace owner or admin.invite_requires_loginReturned by POST /v1/auth/invite/accept when no session exists. The server stashes the invite as a handoff cookie so it can be completed after sign-in.method_not_allowedReturned when the request method (GET, POST, etc.) is not supported by the endpoint at this path. Check the API reference for the correct method.mpesa.unavailableReturned when an M-Pesa top-up is attempted while M-Pesa is unavailable, or on a wallet that is not in KES.not_foundReturned when a resource cannot be found and no subsystem-specific not-found code exists for the endpoint. Prefer module-specific codes where available.numbers.already_claimedReturned when a number claim targets a number that is already assigned. Choose a different available number.numbers.busyReturned with 503 and Retry-After when a number claim or trial conversion lost a race with another change to the same number on every attempt. Nothing is debited.numbers.byo_requires_trunkReturned by POST /v1/numbers/byo when the workspace has no SIP trunk, or its trunk has not yet reached active. Connect and verify a trunk before adding numbers.numbers.credential_limit_reachedReturned when creating a SIP credential would exceed the per-number cap on active credentials. Revoke one to free a slot.numbers.e164_takenReturned by POST /v1/numbers/byo when the number is already on Sautikit, as a Sautikit number or one another workspace brought. A number can exist once.numbers.extension_invalidReturned when an internal extension is not exactly four digits. Send four digits, or leave the field out.numbers.extension_takenReturned when assigning an internal extension that another active credential in the same workspace already holds. Extensions are unique per workspace.numbers.invalid_routing_urlReturned by PUT /v1/numbers/{id}/routing when the URL does not parse, uses a non-http/https scheme, or has an empty host segment.numbers.not_assignedReturned when a release targets a number that has no workspace assignment. Check the number ID and its status.numbers.not_foundReturned when a number operation targets an ID that does not exist or belongs to a different workspace. Verify the number ID and workspace context.numbers.price_changedReturned when a number claim carries expected_monthly_minor and the monthly price the claim would charge is different. Nothing is debited.numbers.price_missingReturned when a number claim is attempted but the number has no price in the workspace's wallet currency. Choose another number or contact support.numbers.retiredReturned when a claim targets a number that has been withdrawn. Choose a different number.numbers.series_invalidReturned when a series create or generate request has an end suffix not greater than start, a range exceeding 10,000, or no voice/sms/webrtc capability selected.numbers.series_not_activeReturned when inventory generation is attempted on a retired or inactive series. The series must be in active status to generate new numbers.numbers.sip_config_unavailableReturned when SIP settings are requested while SIP is unavailable. Retry, and contact support if it continues.numbers.sip_credentials.already_revokedReturned when a rotate or revoke is attempted on a credential that is already in revoked state. No action is taken; the credential remains revoked.numbers.sip_credentials.not_foundReturned when a SIP credential lookup, rotate, or revoke targets an ID that does not exist for the given number. Verify the credential ID.numbers.sip_provisioning_failedReturned when creating, rotating or revoking a SIP credential could not be completed. Nothing is saved. Retry the request.numbers.sip_token_unavailableReturned when a calling token cannot be issued. Retry, and contact support if it continues.numbers.suffix_collisionReturned when a series generation request specifies a suffix range that conflicts with numbers already in inventory. Choose a non-overlapping range.numbers.wallet_unavailableReturned when a number claim cannot proceed because the wallet could not be charged. Nothing is charged. Retry shortly.paystack.unavailableReturned when a card top-up cannot be started because the payment provider is unavailable. Retry shortly, or top up by M-Pesa.provider.has_active_seriesReturned when a provider delete or retire is attempted while active series exist. Retire all associated series before removing the provider.provider.invalid_credentialsReturned when a provider create or update request has SIP credentials that fail validation. Fix the hostname, port, or password and resubmit.rate_limit.exceededReturned with 429 when an IP address passes 1,200 requests a minute or an API key passes 600. Some routes, such as sign-in, have a lower limit of their own.ratelimit.concurrent_cap_reachedReturned with 429 and Retry-After of 1 when a workspace already has 10 requests in flight on the call routes. The refused request places no call and debits nothing.sip_trunk.already_existsReturned by POST /v1/sip-trunk when a trunk is already connected. A workspace has one trunk. Use PUT to change it.sip_trunk.in_useReturned by DELETE /v1/sip-trunk when one or more of your own numbers are still on the trunk. Release those numbers first.sip_trunk.invalidReturned by PUT /v1/sip-trunk when a required field is missing or malformed for the submitted auth_mode. Fix the field named in the message and re-submit.sip_trunk.not_foundReturned by GET, PUT and DELETE /v1/sip-trunk when the workspace has no trunk connected. Connect one with PUT /v1/sip-trunk.sip_trunk.provisioning_failedSeen as last_error on a trunk that stays at pending_approval or moves to failed after review. You cannot retry it yourself; contact support.storage.tier_invalidReturned when PUT /v1/storage/tier specifies a tier_mb not in the allowed set of 100, 1024, 4096, or 51200. Use an exact allowed value.storage.tier_switch_failedReturned when a storage size change could not be saved. The size may not have changed; check it before you retry.topup.not_foundReturned when a top-up status or detail request references an ID that is absent or belongs to a different workspace. Verify the ID and workspace context.validation.bad_requestReturned when a request fails basic shape validation before reaching business logic. The message field carries the specific failure detail.validation.invalid_cursorReturned when a cursor query parameter cannot be decoded or does not match the current filter. Generate a new cursor by starting pagination from the first page.wallet.adjustment_invalid_kindReturned by the admin wallet adjustment endpoint when the kind field is not one of manual_credit, manual_debit, refund, or fee_waiver.wallet.currency_mismatchReturned when a wallet operation specifies a currency that differs from the currency the wallet was provisioned with. Each workspace wallet is single-currency.wallet.insufficient_fundsReturned with 402 when a call, number claim or other charge needs more than the wallet holds. Top up by M-Pesa or card, then retry.wallet.invalid_amountReturned when an amount field fails validation. Debits and credits must be positive integers in minor currency units; thresholds must be non-negative.wallet.not_foundReturned when a wallet operation is attempted before the workspace wallet is provisioned. Contact support or complete the onboarding flow to provision it.wallet.topup_below_minimumReturned when a top-up request is below the configured minimum for the wallet's currency. Increase the amount to meet the minimum floor and retry.webhooks.create_failedReturned when POST /v1/webhooks encounters an internal failure . Retryable with the same Idempotency-Key and body.webhooks.delete_failedReturned when DELETE /v1/webhooks/{id} encounters an internal failure. The subscription may or may not have been deleted; verify state before retrying.webhooks.deliver.secret_unsetShown as last_error on a delivery that could not be signed. Call POST /v1/webhooks/{id}/rotate-secret to set a secret.webhooks.delivery_not_retryableReturned when a manual retry is requested for a delivery that is already succeeded or dead_letter. Terminal deliveries cannot be re-queued.webhooks.dispatcher_unavailableReturned when a webhook test or manual retry is requested while delivery is unavailable. Retry shortly.webhooks.event_unsupportedReturned on POST or PATCH /v1/webhooks when an events entry is not a known event name or wildcard. Correct the entry and resubmit.webhooks.list_failedReturned when GET /v1/webhooks encounters an internal failure. Retryable with exponential backoff per the 5xx policy.webhooks.not_foundReturned when a subscription lookup, update, delete, or delivery query targets an ID that does not exist or is cross-workspace. Verify the subscription ID.webhooks.patch_failedReturned when PATCH /v1/webhooks/{id} encounters an internal failure . Retryable with exponential backoff per the 5xx policy.webhooks.rotate_secret_failedReturned when POST /v1/webhooks/{id}/rotate-secret encounters an internal failure. The secret may not have been updated; retry before updating your receiver.