Error Codes

Complete reference of API error codes and field validation errors returned by the Talkif API.

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
`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_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.
`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.
`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.

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.

Rate Limiting

Code	Status	Description
`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.
`recording_service_not_configured`	503	Recording Service Not Configured Recording storage is not configured on this deployment. Contact your administrator to enable recording.
`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)