> 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 backend 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": "Recording",
  "call_id": "c1a2b3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "control_id": "b9f8e7d6-4a3b-2c1d-0e9f-8a7b6c5d4e3f"
}
```

| 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.                                                                                                                                                                                                                                    |
| `control_id` | Your 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.

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

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

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

```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.** The protocol `version` your connection sent doesn't support this request.                                    |
| `-32002` | **Authentication failed.** Your credentials were rejected.                                                                             |
| `-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`. |
| `-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` 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](/docs/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

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

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

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

Open the socket and log in with your first message.