> This page is for APIs.

> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# Errors

> Every Relay response carries a code and message your client checks for success or failure.

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:

```json
{
  "code": "200",
  "message": "Success",
  "call_id": "c1a2b3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}
```

| Field     | Description                                                                                                                                                                                                                                                                                                                        |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`    | The 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](#identifier-codes)). |
| `message` | A human-readable description of the result. On failure, it explains what went wrong. The exact text varies by command.                                                                                                                                                                                                             |
| `call_id` | The 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.

```javascript
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

| Code    | Meaning                                                                                                                                     |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `"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:

| Code                      | Meaning                                                                   |
| ------------------------- | ------------------------------------------------------------------------- |
| `"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:

```json
{
  "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`:

```json
{
  "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:

| Code     | Meaning                                                                                                                                               |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-32000` | **Timeout.** The request timed out inside SignalWire. Retry it.                                                                                       |
| `-32001` | **Version incompatible.** Call Fabric requests need a connection opened with protocol version `4.0.0`.                                                |
| `-32002` | **Authentication failed.** Your token was rejected or has expired.                                                                                    |
| `-32003` | **Not allowed.** Your credentials don't carry the scope this request needs.                                                                           |
| `-32004` | **Not available.** The service that handles this request couldn't be reached. Retry later.                                                            |
| `-32005` | **Connection limit reached.** Your project already has the maximum number of open Relay connections. Returned on `signalwire.connect`.                |
| `-32600` | **Invalid request.** The request doesn't apply to this connection — for example, a Call Fabric request on a token that doesn't identify a subscriber. |
| `-32601` | **Method not found.** The method isn't recognized.                                                                                                    |
| `-32602` | **Invalid params.** A required parameter is missing or malformed.                                                                                     |
| `-32603` | **Internal error.** Something went wrong on SignalWire's side.                                                                                        |

> **Note**
>
> 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](/docs/browser-sdk/v4/guides/overview) 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

#### [Overview](/docs/apis/relay/client)

How a Relay connection works end to end, and what each service does.

#### [Authentication](/docs/apis/relay/client/authentication)

Open the socket and log in with your first message.