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": "Success",
"call_id": "c1a2b3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}
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.

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.
if (result.code !== "200") {
console.error(`Request 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. Fix the request before retrying.
"403"Forbidden. You don’t have permission for this action, or it doesn’t apply here — for example, muting another participant on a 1:1 call.
"404"Not found. The call or member the request targeted doesn’t exist — often because the call has already ended.
"409"Conflict. The request clashes with the call’s current state.
"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": "404",
"message": "Not found",
"call_id": "c1a2b3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}

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. Call Fabric requests need a connection opened with protocol version 4.0.0.
-32002Authentication failed. Your token was rejected or has expired.
-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.
-32600Invalid request. The request doesn’t apply to this connection — for example, a Call Fabric request on a token that doesn’t identify a subscriber.
-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 that sends a rejected Relay JWT. Fix the request and open a new connection. Errors on other requests leave the connection open, including a rejected Subscriber Access Token on signalwire.reauthenticate.

Using an SDK

The Browser SDK surfaces this result for you — successful commands resolve with a result you can inspect, and failures are raised in JavaScript’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