Error Event

Reported when something the service could not do goes wrong during a call — an action that failed validation, a speech provider that could not be reached, a synthesis that failed. Before this event, most of these failures were only visible in sipgate's logs; now your application can see and react to them.

The event is additive: it does not replace the existing sms_failed event or the transfer_failed_reason field on session_start, which continue to work unchanged.

Event Structure

{
  "type": "error",
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "account-123",
    "phone_number": "1234567890",
    "from_phone_number": "9876543210",
    "to_phone_number": "1234567890"
  },
  "code": "transcription_switch_failed",
  "severity": "warning",
  "message": "The requested transcription provider could not be reached. The session continues with the previous provider.",
  "action_type": "configure_transcription"
}

Fields

Field	Type	Required	Description
type	string	Yes	Always "error"
session	object	Yes	Standard session info
code	string	Yes	Stable machine-readable code — branch on this (see below)
severity	string	Yes	warning (the call continues, possibly degraded) or error (the intended effect did not happen; you likely need to act)
message	string	Yes	Human-readable detail. For logging, not for control flow
action_type	string	No	The action that triggered the error, when one was involved (e.g. configure_transcription, speak, transfer)

Branch on code, and use severity to filter noise without having to know every code. New codes may be added over time — treat an unknown code the way you would treat internal_error.

Codes

code	severity	Meaning
action_invalid	error	An action you sent could not be parsed or failed validation
action_unknown_session	error	An action referenced a session that is no longer active
transcription_unavailable	warning	The speech-recognition provider could not be reached; the call continues, but recognition may be degraded
transcription_switch_failed	warning	A requested configure_transcription switch could not be applied; the previous provider stays in use
synthesis_unavailable	error	Speech synthesis failed and the spoken output was dropped
transfer_target_invalid	error	A transfer request was rejected or could not be placed
internal_error	error	An unexpected internal failure while handling the call

The message is intentionally generic and never contains internal technical detail. Use code and severity to drive behaviour, and message only for your own logs.

Response

Over HTTP each event is a request, so you may answer an error event with action(s) — for example, respond to synthesis_unavailable with a transfer to a human. Returning 204 No Content is also fine; the event is otherwise purely diagnostic.

Over WebSocket there is no per-event response channel, so the event is diagnostic only — any actions you send are handled independently of it.

Examples

Node.js

app.post('/webhook', (req, res) => {
  const event = req.body;

  if (event.type === 'error') {
    console.error(`[${event.severity}] ${event.code}: ${event.message}`);

    // React to the failures that matter to you; ignore the rest.
    if (event.code === 'synthesis_unavailable') {
      return res.send({ type: 'transfer', session_id: event.session.id,
                        target_phone_number: '+49301112223' });
    }
    return res.sendStatus(204);
  }
});

Python

@app.route('/webhook', methods=['POST'])
def webhook():
    event = request.json

    if event['type'] == 'error':
        app.logger.error("[%s] %s: %s",
                         event['severity'], event['code'], event['message'])
        if event['code'] == 'synthesis_unavailable':
            return jsonify({'type': 'transfer',
                            'session_id': event['session']['id'],
                            'target_phone_number': '+49301112223'})
        return '', 204

Related

• SMS Failed — a dedicated event for failed send_sms actions (kept separate; still supported).
• Failed Transfer — transfer_failed_reason on session_start reports the outcome of a placed transfer that returned the caller. transfer_target_invalid here is different: it fires when the transfer request itself could not be placed.

Next Steps

• Event Types - Overview of all events
• Action Types - Actions you can send in response