Skip to main content

Error Codes

When an error occurs while processing a call, the payload's errors[] carries one or more error objects. This page is the reference for the structure of the error object and the possible code values.

Error object structure​

FieldTypeRequiredExampleHow to use it
codestringrequired"CALL_CONNECTION_FAILED"Error category code. One of the values listed below. Use as a switch key.
messagestringrequired"Failed to initiate or connect the call."Fixed English message per category. For display / logging.
timestampstring (ISO8601)required"2026-05-12T10:23:45.000Z"Error occurrence time (UTC, millisecond precision). Use for time-ordered sorting.
Important

Detect errors by checking that errors is non-empty. data.callStatus may contain transitional statuses such as CALLING even when an error occurred — it is not fixed to ERROR.

Possible code values​

code is one of 6 error categories that describe what happened and what to do about it.

codeMeaningImpact on the callRecommended action
CALL_NOT_PERMITTEDThe call was not permitted (international dialing restriction, suspected fraud, etc.)The call was not placedVerify the destination; contact support to lift restrictions
CALL_CONNECTION_FAILEDFailed to initiate or connect the call (including carrier-side issues)The call was not placedRetry later
CALL_INTERRUPTEDA problem occurred during the call and it did not complete normallyThe call may have been cut offDecide whether to redial
CALL_RESULT_PROCESSING_FAILEDThe call finished, but processing of the results (transcript, analysis, saving) failedThe call did take place. Some result data may be missingDo not redial. Contact support if you need the data
INTERNAL_ERRORAn internal Recho error (e.g. a call stuck without status updates was detected)Depends — check data.callStatusContact support if it persists
UNKNOWN_ERRORAn unexpected error that does not fall into any category aboveDepends — check data.callStatusContact support if it persists
info

Categories may be added in future releases. Any addition will be announced by updating this page. Receivers must handle unknown codes gracefully (e.g. log via the default arm of a switch statement).

Categories that need special attention​

  • CALL_RESULT_PROCESSING_FAILED is not a failed call. The call (the conversation with the recipient) did take place. Redialing because of this error would call the recipient twice.
  • When you need an investigation, contact support with the callId (data.callId). Recho can look up the detailed error information on our side.

Changes from the previous error codes​

Previously, implementation-specific detail codes such as NETWORK_ERROR and STALE_CALLING_DETECTED were delivered. They are now consolidated into the 6 categories above, and the where / phase / stacktrace fields have been removed from the error object. Migrate receiver implementations that switch on the old codes as follows.

Old codeNew code
INTERNATIONAL_PERMISSION_ERRORCALL_NOT_PERMITTED
TWILIO_API_ERROR, CALL_INITIATION_ERROR, GEMINI_API_UNAVAILABLECALL_CONNECTION_FAILED
WEBSOCKET_CONNECTION_FAILED, VOICEAI_PROCESSING_ERROR, PRE_VOICEAI_RUNNING_FAILED, STATUS_UPDATE_TO_CALLING_FAILED, STATUS_UPDATE_TO_CONCURRENCY_LIMIT_EXCEEDED_FAILEDCALL_INTERRUPTED
POST_VOICEAI_RUNNING_FAILED, ANALYZER_FAILED, GEMINI_ANALYZER_FAILED, HISTORY_FORMAT_FAILED, CALL_LOG_SAVE_FAILED, STATUS_UPDATE_TO_CLOSING_FAILED, STATUS_UPDATE_TO_FINAL_STATUS_FAILED, STATUS_UPDATE_IN_CALLBACK_FAILED, CALLBACK_PROCESSING_FAILEDCALL_RESULT_PROCESSING_FAILED
STALE_CALLING_DETECTED, STALE_CLOSING_DETECTED, STALE_REQUESTED_DETECTED, STALE_CONNECTING_DETECTEDINTERNAL_ERROR
INVALID_REQUEST_ID, NETWORK_ERROR, TIMEOUT— (retired; no longer emitted)