> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> HTTP errors, command exit codes and retry behavior.

A `200` from `POST /v1/workspaces/{workspace_id}/shell` means the server ran
the line, not that the line succeeded: check `exit_code`. Most API errors return
JSON with a `detail` message, but an auth or `Host` refusal can be plain text,
so check `Content-Type` before parsing. Requests past a limit answer `429` with
`Retry-After` ([rate limits](https://docs.mirage.strukto.ai/home/access/http.md#rate-limits)).

## HTTP status codes

| Status | Meaning | Recovery |
| - | - | - |
| `400` | Malformed request, disallowed host or disallowed browser origin. | Check the body, API host and browser origin. |
| `401` | Missing or incorrect token. | Send a valid bearer token; sign in again if it expired. |
| `403` | A policy or mount mode refused the call. | Check workspace policies and mount permissions. |
| `404` | The workspace, session, job or file does not exist. | Verify the identifier or file path. |
| `409` | An identifier is taken, the workspace is busy or a file changed since it was read. | Resolve the conflict before retrying; see the workspace example below. |
| `413` | A request body, multipart part, or stdin exceeds its size limit. | Reduce the input size and check the endpoint's limits. |
| `422` | Request fields failed validation. | Correct the fields named in `detail`. |
| `429` | A rate limit or session limit was reached. | Respect `Retry-After` when present; reduce the request rate or close unused sessions. |
| `499` | A running shell job was canceled. | Check its output and any side effects before rerunning it. |
| `500` | A job or server operation failed internally. | Inspect `detail` and the server logs; check for side effects before retrying. |
| `501` | A saved-config operation requires a server configured for one account. | Check the deployment's saved-configuration support. |
| `503` | The server reached its workspace limit or is shutting down. | Retry after capacity or availability recovers. |
| `507` | A filesystem operation exceeds its backend's storage capacity or quota. | Free space or increase the backend's capacity before retrying. |

Each endpoint's **Errors** section lists its documented failures. The complete
[OpenAPI contract](https://github.com/strukto-ai/mirage/blob/main/docs/openapi.yaml)
retains every response schema. JSON errors can
include `errno` and `refusal` alongside `detail`. Those fields describe filesystem
errors and policy refusals when available.

For oversized JSON requests, TypeScript can return HTTP `413` with `statusCode`,
`code`, `error`, and `message` fields. Read `message` when `detail` is absent.

The readiness endpoint uses a different body: HTTP `503` returns
`{"status": "full"}` or `{"status": "shutting_down"}` when the server cannot
accept new workspaces.

## Examples

### Missing or invalid credentials

The TypeScript daemon returns HTTP `401` with JSON:

```json theme={null}
{"detail": "Unauthorized"}
```

The Python daemon returns the same status with `Content-Type: text/plain`:

```text theme={null}
Unauthorized
```

Check `Content-Type` before decoding the body. Supply a valid token before retrying.
See [Authentication](https://docs.mirage.strukto.ai/api/authentication.md).

### Workspace identifier conflict

Creating `demo` again with a different configuration returns HTTP `409`:

```json theme={null}
{"detail": "workspace id already exists: 'demo'"}
```

Choose another identifier for a different workspace. Retrying the original
configuration with the same identifier returns HTTP `200` and the existing
workspace, with the same response shape as a successful `201` creation.

### Invalid request field

Sending a numeric workspace `id` returns HTTP `422`:

```json theme={null}
{
  "detail": [
    {
      "type": "string_type",
      "loc": ["body", "id"],
      "msg": "Input should be a valid string",
      "input": 4
    }
  ]
}
```

`loc` identifies the invalid field. Change `id` to a string before retrying.
Validation messages can differ between server implementations.

## Shell exit codes

A completed shell request can return HTTP `200` with a nonzero `exit_code`.
Inspect `exit_code`, `stdout`, `stderr` and `refusal` before treating the command
as successful. The response's HTTP status describes the request, while
`exit_code` describes the shell command.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.