Error Codes
When an error occurs while processing a call, the payload's body.errors[] carries one or more error objects. This page is the reference for the structure of the error object and the possible code values.
The error object structure and the error code scheme are scheduled to change to an easier-to-consume format. Details and timing will be announced on this page once finalized.
Error object structure
| Field | Type | Required | Example | How to use it |
|---|---|---|---|---|
code | string | required | "NETWORK_ERROR" | Machine-readable error code. One of the values listed below. Use as a switch key on the receiver side. |
message | string | required | "Connection timed out" | Human-readable error message (Japanese or English). Display / log purposes. |
timestamp | string (ISO8601) | required | "2026-05-12T10:23:45.000Z" | Error occurrence time (UTC, millisecond precision). Use for time-ordered sorting. |
where | string | required | "OutboundCallAdapter.connect" | Origin of the error (class / function / module name). Reference info for Recho-side investigation. |
phase | string | required | "CONNECTING" | Phase of the call at which the error occurred. Use for root-cause categorization and aggregation. |
stacktrace | string | required | "Error: Connection timed out\n at ..." | Stack trace. May be empty (e.g. for errors originating outside the system). For first-pass investigation. |
Detect errors by checking that body.errors is non-empty. body.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 always one of the values in the table below. If an unexpected internal error occurs that is not in the list, it is delivered as UNKNOWN_ERROR. New codes may be added in future releases, so receivers must handle unknown codes gracefully (e.g. log via the default arm of a switch statement).
The Category column indicates the rough stage where the error occurred:
- Call failed … the call itself could not be placed
- In-call … failed during the live call (connection, AI processing, status transitions)
- Post-call … failed after the call ended (analysis, log persistence, post-processing)
- Internal monitoring … detected that the call status had not been updated for an extended period
- Other … unexpected errors that do not fall into the categories above
| code | Category | Description |
|---|---|---|
INTERNATIONAL_PERMISSION_ERROR | Call failed | International dialing blocked — suspected fraudulent call / no international dialing permission. |
TWILIO_API_ERROR | Call failed | API error on the telephony carrier (Twilio) side (non-permission, generic). |
CALL_INITIATION_ERROR | Call failed | Call initiation failed (generic code regardless of connection method). |
INVALID_REQUEST_ID | Call failed | Invalid request ID or phone number. |
NETWORK_ERROR | In-call | Generic network I/O failure. |
TIMEOUT | In-call | External request or internal processing timed out. |
WEBSOCKET_CONNECTION_FAILED | In-call | Failed to connect to the voice AI. |
VOICEAI_PROCESSING_ERROR | In-call | Voice AI processing error during the call. |
PRE_VOICEAI_RUNNING_FAILED | In-call | Pre-call preparation failed (config fetch, etc.). |
STATUS_UPDATE_TO_CALLING_FAILED | In-call | Transition to CALLING failed. |
STATUS_UPDATE_TO_CLOSING_FAILED | In-call | Transition to CLOSING failed. |
STATUS_UPDATE_TO_CONCURRENCY_LIMIT_EXCEEDED_FAILED | In-call | Transition to CONCURRENCY_LIMIT_EXCEEDED failed. |
POST_VOICEAI_RUNNING_FAILED | Post-call | Post-call processing failed. |
ANALYZER_FAILED | Post-call | Call-result analysis failed. |
GEMINI_ANALYZER_FAILED | Post-call | Analysis by the AI model (Gemini) failed. |
HISTORY_FORMAT_FAILED | Post-call | Failed to format the conversation history. |
CALL_LOG_SAVE_FAILED | Post-call | Failed to save the call log. |
GEMINI_API_UNAVAILABLE | Post-call | The AI model (Gemini) API is unavailable. |
STATUS_UPDATE_TO_FINAL_STATUS_FAILED | Post-call | Transition to a final status (COMPLETED, etc.) failed. |
STATUS_UPDATE_IN_CALLBACK_FAILED | Post-call | Status-update failure inside post-disconnect processing. |
CALLBACK_PROCESSING_FAILED | Post-call | General failure inside post-disconnect processing. |
STALE_CALLING_DETECTED | Internal monitoring | Call stuck in CALLING state past the allowed duration (outbound and inbound). |
STALE_CLOSING_DETECTED | Internal monitoring | Call stuck in CLOSING state past the allowed duration (outbound and inbound). |
STALE_REQUESTED_DETECTED | Internal monitoring | Call stuck in REQUESTED state past the allowed duration (outbound only). |
STALE_CONNECTING_DETECTED | Internal monitoring | Call stuck in CONNECTING state past the allowed duration (inbound only). |
UNKNOWN_ERROR | Other | Unexpected error that does not fall into any of the codes above. |
New codes may be added in future releases. Any addition will be announced by updating the list on this page.
Related pages
- Payload Spec — the overall payload structure and where
body.errors[]fits - Call Status Reference — why callStatus must not be used for error detection
- Retry Policy — redelivery rules on failed deliveries