Skip to navigation

Errors

View as MarkdownOpen in Claude

Relay doesn’t fail with HTTP status codes — there’s no HTTP response on a WebSocket. A request can fail in one of two ways, and you handle both:

  • A failing result. The command reached the call or service and came back with a result whose code isn’t "200". This is how most command failures arrive.
  • A JSON-RPC error. The request was rejected before it ran — the connection’s protocol version, credentials, or scopes don’t allow it, or a parameter is missing or malformed. The response carries an error object instead of a result.

A response carries one or the other, never both.

The result shape

A typical result looks like this:

{
"code": "200",
"message": "Recording",
"call_id": "c1a2b3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"control_id": "b9f8e7d6-4a3b-2c1d-0e9f-8a7b6c5d4e3f"
}
FieldDescription
codeThe result code, as a string. "200" means success; any other value means the request failed. Most failures carry a numeric code such as "404"; a failure SignalWire hits before your request is carried out carries a lowercase identifier such as response_timeout instead (see Identifier codes).
messageA human-readable description of the result. On failure, it explains what went wrong. The exact text varies by command.
call_idThe call this result is for, echoed from your request. Present when the command acts on a call.
control_idYour control identifier for the started action, echoed when your request included one.

Checking for success

The one thing to check is code, and remember it’s a string, not a number:

  • "200" — the request succeeded.
  • Anything else — the request failed, and message explains why.
result = call.play(url="https://example.com/audio.mp3")
if result.code != "200":
print(f"Play failed: {result.message}")

Numeric codes mirror familiar HTTP status conventions, so a "4xx" value means the request was rejected and a "5xx" value means something went wrong on SignalWire’s side.

Common codes

CodeMeaning
"200"Success. The command was accepted.
"400"Bad request. A parameter was missing or invalid — for example, requesting a codec the call type doesn’t support. Fix the request before retrying.
"403"Forbidden. The call the request targets belongs to a different project than your credentials.
"404"Not found. The call or resource the request targeted doesn’t exist — often because it has already ended.
"405"Not allowed. The command can’t run on the call as it stands — for example, a command sent to a call that hasn’t started yet, or a dial on a call that’s already active.
"409"Conflict. The request clashes with the call’s current state — for example, starting transcription on a call that already has it running.
"410"Gone. The call existed but has ended.
"500"Server error. Something went wrong on SignalWire’s side.

Identifier codes

When SignalWire can’t carry out your request at all, for example because the service that handles it didn’t answer in time, code is a lowercase identifier instead of a number. Treat any of these as a failure:

CodeMeaning
"response_timeout"The request timed out before it was carried out.
"not_available"The service that handles this request couldn’t be reached. Retry later.
"internal_error"Something went wrong on SignalWire’s side.
"parse_error"SignalWire couldn’t read the response to your request.
"invalid_params"A required parameter is missing or malformed.
"invalid_request"The request doesn’t apply to this connection.
"method_not_found"The method isn’t recognized.
"not_allowed"The request isn’t permitted for your credentials.
"authentication_failed"Your credentials were rejected.
"version_incompatible"The protocol version your connection sent doesn’t support this request.
"unknown:<n>"Any other failure, where <n> is the underlying JSON-RPC error code.

Examples

A failed request returns the same shape, with a non-"200" code and a message explaining the cause:

{
"code": "409",
"message": "Transcribe is already in progress",
"call_id": "c1a2b3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"control_id": "b9f8e7d6-4a3b-2c1d-0e9f-8a7b6c5d4e3f"
}

JSON-RPC errors

When a request is rejected before it runs, the response has an error object in place of result:

{
"jsonrpc": "2.0",
"id": "4e1f7a9c-2b3d-4c5e-8f6a-7b8c9d0e1f2a",
"error": {
"code": -32602,
"message": "Invalid params",
"original_request": { "jsonrpc": "2.0", "id": "4e1f7a9c-2b3d-4c5e-8f6a-7b8c9d0e1f2a", "method": "...", "params": {} }
}
}

code is a negative integer and original_request echoes the request that failed. The codes you can see:

CodeMeaning
-32000Timeout. The request timed out inside SignalWire. Retry it.
-32001Version incompatible. The protocol version your connection sent doesn’t support this request.
-32002Authentication failed. Your credentials were rejected.
-32003Not allowed. Your credentials don’t carry the scope this request needs.
-32004Not available. The service that handles this request couldn’t be reached. Retry later.
-32005Connection limit reached. Your project already has the maximum number of open Relay connections. Returned on signalwire.connect.
-32601Method not found. The method isn’t recognized.
-32602Invalid params. A required parameter is missing or malformed.
-32603Internal error. Something went wrong on SignalWire’s side.

A JSON-RPC error on signalwire.connect closes the socket, and so does a signalwire.reauthenticate whose credentials are rejected. Fix the request and open a new connection. Errors on other requests leave the connection open.

Using an SDK

The Server SDKs surface this result for you — successful commands return a result object you can inspect, and failures are raised or returned in your language’s idiomatic style instead of leaving you to compare code strings by hand. The code and message are still there when you need the underlying detail.

Next steps