Error Codes | Talkif Docs

All API errors follow a consistent response shape:

{
  "code": "insufficient_balance",
  "status": 402,
  "title": "Insufficient Balance",
  "detail": "Account balance is too low for this operation — add funds to continue",
  "requestId": "019ce738-dfc6-7740-9fc8-db47b7230650"
}

Field	Type	Description
`code`	`string`	Machine-readable error identifier — use this for programmatic handling
`status`	`number`	HTTP status code
`title`	`string`	Short human-readable summary
`detail`	`string`	Detailed explanation of what went wrong
`requestId`	`string`	Unique request ID for support and debugging

When a validation_failed error occurs, an additional errors array is included with per-field details:

{
  "code": "validation_failed",
  "status": 400,
  "title": "Validation Failed",
  "detail": "One or more fields failed validation",
  "requestId": "...",
  "errors": [
    {
      "field": "email",
      "code": "invalid_email_format",
      "message": "Email format is invalid (must conform to RFC 5322)"
    }
  ]
}

Api Keys

Code	Status	Description
`api_key_expired`	401	API Key Expired — This API key has passed its expiration date. Create a new API key to restore access.
`api_key_invalid`	401	API Key Invalid — The API key is not recognized or has been deleted. Create a new API key from your dashboard.
`api_key_revoked`	401	API Key Revoked — This API key has been revoked and can no longer be used. Create a new API key if needed.
`api_key_insufficient_scope`	403	API Key Insufficient Scope — This API key does not have the required scope for this operation. Create a new key with the appropriate scopes, or use a JWT.
`api_key_ip_restricted`	403	API Key IP Restricted — The request IP address is not in this API key’s allowed IP list. Update the key’s IP restrictions or use a different key.
`api_key_not_allowed`	403	API Key Not Allowed — API key authentication is not permitted on this endpoint. Use a JWT Bearer token instead.
`api_key_limit_reached`	422	API Key Limit Reached — You have reached the maximum number of API keys for this account. Delete unused keys before creating new ones.

Authentication

Code	Status	Description
`account_header_missing`	400	Account Header Missing — Account-scoped requests authenticated with JWT require the X-Account-Id header. Use GET /accounts to list accessible accounts, or include the header from the frontend client state.
`email_already_verified`	400	Email Already Verified — This email address has already been verified. No further action is needed.
`email_verification_code_expired`	400	Email Verification Code Expired — The email verification code has expired (codes are valid for 15 minutes). Request a new verification code.
`email_verification_code_invalid`	400	Email Verification Code Invalid — The email verification code is incorrect. Check the code and try again, or request a new one.
`email_verification_code_used`	400	Email Verification Code Used — This email verification code has already been used. Request a new code if you need to verify again.
`mfa_already_enabled`	400	MFA Already Enabled — Multi-factor authentication is already enabled on this account. No further setup is needed.
`mfa_code_invalid`	400	MFA Code Invalid — The MFA code is incorrect or has expired. Enter the current code from your authenticator app.
`mfa_not_enabled`	400	MFA Not Enabled — Multi-factor authentication is not enabled on this account. Call the MFA setup endpoint first.
`mfa_not_setup`	400	MFA Not Setup — MFA setup has not been initiated. Call the MFA setup endpoint to receive a TOTP secret before verifying.
`mfa_token_invalid`	400	MFA Token Invalid — The MFA token is invalid or has expired. Log in again and complete the MFA challenge.
`password_current_incorrect`	400	Current Password Incorrect — The current password you provided is incorrect. Try again with the correct password.
`password_reset_token_expired`	400	Password Reset Token Expired — The password reset token has expired (tokens are valid for 1 hour). Request a new password reset email.
`password_reset_token_invalid`	400	Password Reset Token Invalid — The password reset token is invalid or corrupted. Request a new password reset email.
`password_reset_token_used`	400	Password Reset Token Used — This password reset token has already been used. Request a new password reset email if needed.
`password_same_as_current`	400	Password Same As Current — Your new password must be different from your current password. Choose a different password.
`phone_already_verified`	400	Phone Already Verified — This phone number has already been verified. No further action is needed.
`phone_number_missing`	400	Phone Number Missing — No phone number is associated with this account. Add a phone number before attempting verification.
`phone_verification_code_expired`	400	Phone Verification Code Expired — The phone verification code has expired (codes are valid for 10 minutes). Request a new verification code.
`phone_verification_code_invalid`	400	Phone Verification Code Invalid — The phone verification code is incorrect. Check the code and try again, or request a new one.
`phone_verification_code_used`	400	Phone Verification Code Used — This phone verification code has already been used. Request a new code if you need to verify again.
`invalid_credentials`	401	Invalid Credentials — The email and password combination does not match any account. Double-check your credentials or use the forgot password flow.
`refresh_token_invalid`	401	Refresh Token Invalid — The refresh token is invalid, has been revoked, or has expired. Log in again to obtain new tokens.
`token_expired`	401	Token Expired — Your access token has expired. Use your refresh token to obtain a new access token, or log in again.
`token_invalid`	401	Token Invalid — The provided token could not be validated. Clear your stored tokens and log in again.
`token_missing`	401	Token Missing — This endpoint requires authentication. Include a valid Bearer token in the Authorization header.
`unauthorized`	401	Unauthorized — This endpoint requires authentication. Include a valid Bearer token or API key in your request.

Authorization

Code	Status	Description
`account_access_denied`	403	Account Access Denied — You do not have permission to access this account. Verify the account ID or request access from the account owner.
`account_suspended`	403	Account Suspended — This account has been suspended by an administrator. Contact support to resolve the suspension.
`forbidden`	403	Forbidden — You do not have permission to perform this action. Contact the account owner for access.
`insufficient_permissions`	403	Insufficient Permissions — Your role does not have sufficient permissions for this action. Contact your organization owner or admin.
`not_invitation_recipient`	403	Not Invitation Recipient — This invitation was sent to a different user. Only the intended recipient can accept or decline it.

Business Rules

Code	Status	Description
`business_rule_violation`	422	Business Rule Violation — The request violates a business rule. Check the error detail for specifics.
`invalid_state_transition`	422	Invalid State Transition — This state transition is not allowed from the resource’s current state. Check the resource status before retrying.
`unprocessable_entity`	422	Unprocessable Entity — The request is well-formed but cannot be processed. Check the error detail for the specific reason.

Calls

Code	Status	Description
`flow_not_published`	400	Flow Not Published — The flow must be published before it can be used for calls. Publish the flow from the flow editor.
`phone_number_cannot_initiate_calls`	400	Phone Number Cannot Initiate Calls — This phone number can only receive calls. WhatsApp numbers do not support outbound calling yet — choose a phone number with outbound call capability.
`phone_number_not_active`	400	Phone Number Not Active — This phone number is not in active status. Activate the phone number from your dashboard before using it for calls.
`phone_number_not_verified`	400	Phone Number Not Verified — This phone number must be verified before making outbound calls. Complete the verification process first.
`provider_call_rejected`	400	Provider Call Rejected — The telephony provider rejected the call to this number. The destination may not be enabled for outbound calling from this account.
`call_already_completed`	422	Call Already Completed — This call has already ended and cannot be modified. Fetch the call details to see the final status.
`concurrent_call_limit_exceeded`	422	Concurrent Call Limit Exceeded — You have reached the maximum number of simultaneous active calls for your account. Wait for active calls to end or upgrade your plan.
`contact_on_dnc_list`	422	Contact On DNC List — This phone number is on your account’s Do Not Call list. Remove it from the DNC list before calling, or skip this contact.
`daily_call_limit_exceeded`	422	Daily Call Limit Exceeded — Your daily call quota has been exhausted. The limit resets at midnight UTC, or upgrade your plan for higher limits.
`outside_callable_hours`	422	Outside Callable Hours — This call was blocked because the recipient’s local time is outside legal calling hours (8 AM–9 PM). Schedule the call for an appropriate time.

Conflict

Code	Status	Description
`cannot_delete_has_dependencies`	409	Cannot Delete Has Dependencies — This resource has dependent resources that must be removed first. Check which resources reference it before deleting.
`conflict`	409	Conflict — The request conflicts with the current state of the resource. Fetch the latest state and retry.
`contact_phone_already_exists`	409	Contact Phone Already Exists — A contact with this phone number already exists on this account. Open the existing contact instead, or use a different number.
`email_already_exists`	409	Email Already Exists — An account with this email address already exists. Try logging in instead, or use a different email to register.
`phone_already_exists`	409	Phone Already Exists — An account with this phone number already exists. Try logging in instead, or use a different number.
`resource_already_exists`	409	Resource Already Exists — A resource with these properties already exists. Use a different identifier or update the existing resource.

Flows

Code	Status	Description
`flow_has_connected_phones`	400	Flow Has Connected Phones — This flow cannot be deleted because phone numbers are still connected to it. Disconnect all phone numbers first.
`flow_structure_invalid`	400	Flow Structure Invalid — The flow definition contains structural errors. Check the errors array in the response for specific node and edge issues.
`flow_version_invalid`	400	Flow Version Invalid — The flow version format is invalid. Use semantic versioning format (e.g., 1.0.0).
`flow_function_not_found`	404	Flow Function Not Found — No flow function was found with this ID. Verify the function ID or list functions to find the correct one.
`flow_function_name_exists`	409	Flow Function Name Already Exists — A flow function with this name already exists in your account. Choose a different name.
`flow_name_already_exists`	409	Flow Name Already Exists — A flow with this name already exists in your account. Choose a different name.
`flow_version_conflict`	409	Flow Version Conflict — The flow has been modified since you last loaded it. Fetch the latest version and try again.
`flow_generation_failed`	502	Flow Generation Failed — The AI could not produce a valid flow from this description. Rephrase the request with a clearer goal, or build the flow manually in the editor.

Integrations

Code	Status	Description
`meta_form_already_mapped`	409	Form Already Mapped — This lead form already has a mapping on the integration. Update or delete the existing mapping instead.
`meta_page_already_connected`	409	Page Already Connected — This Facebook page is already connected to an account. Disconnect the existing integration first, or pick a different page.
`meta_lead_unrecoverable`	422	Meta Lead Unrecoverable — This lead can’t be retried. It was submitted without a valid phone number, so re-fetching it from Meta won’t help.
`meta_api_error`	502	Meta API Error — Meta’s API rejected the request. Check the integration status and re-connect if the page tokens have expired.
`meta_not_configured`	503	Meta Integration Not Configured — The Meta (Facebook) integration is not configured on this deployment. Contact your administrator to enable it.

Not Found

Code	Status	Description
`campaign_not_found`	404	Campaign Not Found — No campaign was found with this ID. Verify the campaign ID or list campaigns to find the correct one.
`invitation_not_found`	404	Invitation Not Found — The invitation does not exist or has already been accepted, declined, or revoked.
`not_found`	404	Not Found — The requested resource does not exist or has been deleted. Verify the resource ID.
`resource_not_found`	404	Resource Not Found — The requested resource does not exist or has been deleted. Verify the resource ID.
`schedule_not_found`	404	Schedule Not Found — No call schedule was found with this ID. Verify the schedule ID or list schedules to find the correct one.

Oauth

Code	Status	Description
`cannot_unlink_only_auth`	400	Cannot Unlink Only Auth Method — This is your only authentication method. Set a password or link another OAuth provider before unlinking this one.
`invalid_o_auth_state`	400	Invalid OAuth State — The OAuth state parameter is invalid, expired, or missing. Restart the OAuth flow from the beginning.
`o_auth_not_linked`	404	OAuth Not Linked — No OAuth connection exists for this provider on your account. Link the provider first before attempting to unlink.
`o_auth_already_linked`	409	OAuth Already Linked — This OAuth account is already linked to a different user. Unlink it from the other account first, or use a different OAuth account.
`provider_already_connected`	409	Provider Already Connected — You already have this OAuth provider connected. Unlink the existing connection before linking a new one.
`o_auth_provider_error`	502	OAuth Provider Error — The OAuth provider (e.g., Google) returned an error during authentication. Try again, or check the provider’s status page.

Organizations

Code	Status	Description
`already_organization_member`	409	Already Organization Member — This user is already a member of the organization. No invitation is needed.
`invitation_expired`	410	Invitation Expired — This invitation has expired and is no longer valid. Ask the organization admin to send a new invitation.
`invitation_not_pending`	422	Invitation Not Pending — This invitation has already been accepted, declined, or revoked. It can no longer be acted upon.
`organization_suspended`	422	Organization Suspended — This organization is suspended and cannot accept new members. Contact the organization owner.

Payment

Code	Status	Description
`payment_method_card_only`	400	Payment Method Card Only — Only card payment methods are currently supported. Add a credit or debit card to proceed.
`feature_not_available`	402	Feature Not Available — This feature is not included in your current plan. Upgrade to a higher tier to access it.
`insufficient_balance`	402	Insufficient Balance — Your account balance is too low for this operation. Add funds from the billing page to continue.
`payment_failed`	402	Payment Failed — The payment charge failed (card declined, insufficient funds, or payment processor error). Try a different payment method.
`payment_required`	402	Payment Required — This feature requires payment. Add a payment method and ensure your account has sufficient balance.
`subscription_required`	402	Subscription Required — An active subscription is required for this feature. Upgrade your plan to access it.

Phones

Code	Status	Description
`byoc_only`	400	BYOC Only — This operation is only available for BYOC (Bring Your Own Carrier) providers. It does not apply to system Twilio numbers.
`phone_number_already_connected`	400	Phone Number Already Connected — This phone number is already connected to a flow. Disconnect it from the current flow before connecting to a new one.
`phone_number_not_connected`	400	Phone Number Not Connected — This phone number is not connected to any flow. Connect it to a flow to enable inbound call handling.
`phone_provider_not_active`	400	Phone Provider Not Active — The phone provider is not in active status. Activate the provider before using its phone numbers.
`phone_verification_not_started`	400	Phone Verification Not Started — No caller ID verification is in progress for this number. Start a new verification before checking the status.
`provider_must_be_sip`	400	Provider Must Be SIP — This operation is only available for SIP-type providers. Verify the provider type before proceeding.
`twilio_credentials_required`	400	Twilio Credentials Required — Twilio account credentials (Account SID and Auth Token) are required for this provider type. Provide them in the request.
`verification_only_for_sip`	400	Verification Only For SIP — Caller ID verification is only supported for SIP phone numbers. System Twilio numbers are verified automatically.
`phone_already_registered`	409	Phone Already Registered — This phone number is already registered in the system. Use a different number or check existing phone numbers.
`phone_number_in_use`	409	Phone Number In Use — This phone number is already in use by another user. Use a different phone number.
`cannot_delete_system_provider`	422	Cannot Delete System Provider — System-managed providers cannot be deleted. Only user-created SIP and BYOC providers can be removed.

Promotions

Code	Status	Description
`payment_method_required`	403	Payment Method Required — A payment method on file is required before claiming this promotion. Add a card in billing settings first.
`user_phone_not_verified`	403	Phone Verification Required — Your phone number must be verified before claiming this promotion. Verify your phone in profile settings first.
`coupon_not_found`	404	Coupon Not Found — No coupon exists with this code. Check the code for typos.
`coupon_already_redeemed`	409	Coupon Already Redeemed — You have already redeemed this coupon. Each coupon can be redeemed once per user.
`promotion_not_eligible`	409	Promotion Not Eligible — This promotion cannot be claimed with the provided details. Contact support if you believe this is an error.
`trial_already_claimed`	409	Trial Already Claimed — The trial credit has already been claimed for this user. It can only be claimed once.
`coupon_not_redeemable`	410	Coupon Not Redeemable — This coupon is no longer redeemable — it is inactive, outside its redemption window, or fully redeemed.

Rate Limiting

Code	Status	Description
`assistant_quota_exceeded`	429	Assistant Quota Exceeded — Your assistant usage allowance for this period is exhausted. It resets at meta.resetsAt; topping up your balance also earns extra assistant allowance.
`queue_full`	429	Queue Full — The call queue has reached maximum capacity. Wait for active calls to complete before queuing more.
`rate_limit_exceeded`	429	Rate Limit Exceeded — Too many requests. Wait for the duration specified in meta.retryAfterSecs before retrying.

Scheduling

Code	Status	Description
`invalid_cron_expression`	400	Invalid Cron Expression — The cron expression is malformed. Use standard 5-field cron syntax (minute hour day month weekday).
`invalid_timezone`	400	Invalid Timezone — The timezone identifier is not recognized. Use a valid IANA timezone (e.g., America/New_York, Europe/Istanbul).
`campaign_no_contacts`	422	Campaign Has No Contacts — This campaign has no contacts to call. Add contacts before starting the campaign.
`campaign_not_draft`	422	Campaign Not In Draft State — This campaign is not in draft state and cannot be modified. Only draft campaigns can be edited.
`schedule_already_paused`	422	Schedule Already Paused — This schedule is already paused. No action is needed, or resume it before pausing again.
`schedule_not_paused`	422	Schedule Not Paused — This schedule is not paused and cannot be resumed. Only paused schedules can be resumed.

Server

Code	Status	Description
`recording_not_available`	400	Recording Not Available — No recording is available for this call. The call may not have been recorded, or the recording has been deleted.
`internal_error`	500	Internal Server Error — An unexpected server error occurred. If this persists, contact support with the requestId from this response.
`service_error`	502	Service Error — An external service dependency encountered an error. Retry your request in a few moments.
`email_service_unavailable`	503	Email Service Unavailable — The email delivery service is temporarily unavailable. Retry your request in a few moments.
`no_bots_available`	503	No Bots Available — No healthy bots are currently available in the target region to handle this call. Retry shortly while the bot pool scales up.
`recording_service_not_configured`	503	Recording Service Not Configured — Recording storage is not configured on this deployment. Contact your administrator to enable recording.
`region_saturated`	503	Region Saturated — The target region is at capacity (bot pool plus queue is full). Retry in a moment, or contact support if this persists.
`service_unavailable`	503	Service Unavailable — The service is temporarily unavailable. Retry your request in a few moments.
`sms_service_unavailable`	503	SMS Service Unavailable — The SMS delivery service is temporarily unavailable. Retry your request in a few moments.

Templates

Code	Status	Description
`template_variable_resolution_failed`	400	Template Variable Resolution Failed — One or more template variables could not be resolved. Ensure all required variables are provided in the request.

Validation

Code	Status	Description
`bad_request`	400	Bad Request — The request is malformed or contains invalid parameters. Check the request body and query parameters.
`invalid_id_format`	400	Invalid ID Format — The provided ID is not a valid UUID. Use the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
`invalid_json`	400	Invalid JSON — The request body is not valid JSON. Ensure the body is properly formatted and the Content-Type header is application/json.
`legal_acceptance_required`	400	Legal Acceptance Required — You must accept the required legal documents (Terms of Service, Privacy Policy) before proceeding.
`validation_failed`	400	Validation Failed — One or more request fields failed validation. Check the errors array in the response for field-specific details.
`verification_code_invalid`	400	Verification Code Invalid — The verification code is incorrect. Check the code and try again, or request a new one.

Field Validation

Field-level errors appear in the errors[] array when the response code is validation_failed. Each entry includes the field name, a machine-readable code, and a human-readable message.

Code	Description
`above_maximum`	Value exceeds the maximum allowed threshold
`already_exists`	A resource with this value already exists (uniqueness constraint)
`already_in_use`	This value is already in use by another resource
`below_minimum`	Value is below the minimum allowed threshold
`circular_dependency`	Flow contains a circular dependency between nodes
`edges_required`	Edges array is required in the flow definition
`invalid_edge_reference`	Edge references a node that does not exist in the flow
`invalid_email_format`	Email format is invalid (must conform to RFC 5322)
`invalid_format`	Value format is invalid for this field
`invalid_initial_node`	The specified initial node does not exist in the flow
`invalid_language_code`	Language code is not recognized or not supported
`invalid_model_id`	Model ID does not exist or is disabled for this provider
`invalid_phone_format`	Phone number format is invalid
`mfa_code_invalid_format`	MFA code must be exactly 6 digits
`missing_llm_service`	Flow is missing a required LLM service node
`missing_main_agent`	Flow must contain exactly one main_agent node
`missing_model`	Node is missing the required model field
`missing_stt_language`	STT node is missing the required language setting
`missing_stt_service`	Flow is missing a required STT service node
`missing_tts_service`	Flow is missing a required TTS service node
`missing_tts_voice_id`	TTS node is missing the required voice ID
`multiple_main_agents`	Flow contains multiple main_agent nodes (only one is allowed)
`must_be_gte`	Value must be greater than or equal to the referenced field’s value
`nodes_required`	At least one node is required in the flow definition
`out_of_range`	Value is outside the valid range
`password_too_short`	Password must be at least 8 characters
`password_too_weak`	Password does not meet complexity requirements
`phone_not_e164`	Phone number must be in E.164 format (e.g., +14155552671)
`required`	This field is required but was not provided
`too_long`	Value exceeds the maximum allowed length
`too_short`	Value is below the minimum required length
`unknown_node_type`	Node type is not recognized
`version_invalid_format`	Version must follow semantic versioning format (X.Y.Z)