# Errors (/reference/errors)

The shape of a refusal, what it tells you, which refusals to retry, and every code Marfa answers.



When Marfa refuses a request, it says why in a form a program can act on: a stable code, a message for people, and details that name what went wrong. Branch on the code, never the message. Each operation's page lists the codes that operation can return, and a tool on the [Marfa MCP server](/reference/marfa-mcp-server#tool-errors) answers the same codes.

## The shape of a refusal [#the-shape-of-a-refusal]

A refusal is a JSON body holding one `error` object. Here a key that may read `core.note` but not write it tries to create a note:

```http title="Response"
HTTP/1.1 403 Forbidden
Content-Type: application/json
X-Error-Code: type_not_permitted
X-Request-ID: 01a1f14d-e3b6-7626-aab1-d8ee63685943

{ "error": { "code": "type_not_permitted", "message": "Write access to type \"core.note\" denied", "details": { "grant": { "kind": "type", "name": "core.note", "level": "write" } } } }
```

* **`code`:** one of the codes below, and the value to branch on.
* **`message`:** a sentence for people. It can change.
* **`details`:** an object whose members depend on the refusal, when there is one.
* **`X-Error-Code`:** the code again, so a client or a proxy can read it without parsing the body.
* **`X-Request-ID`:** on every answer. Quote it when you [ask for help](/get-help). Send your own of 1 to 128 letters, digits, underscores and hyphens and Marfa answers with it, except under `/inbound/`.

A few answers differ from this shape:

* A `HEAD` request gets the status and headers with no body.
* `409 version_conflict` and `409 ancestor_unavailable` also carry the item as it is now, in `current` beside `error`, as [Update an item](/reference/api/items/updateItem) shows.
* A page under `/auth/` refuses in plain text or as an HTML page, and an OAuth endpoint under `/oauth/` refuses in the shape its RFC sets ([`errors/envelope`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/errors.md#errorsenvelope)).
* A request whose `Accept` names `text/html` before `application/json` gets an HTML page of the refusal's status, still with `X-Error-Code` ([`errors/html-page`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/errors.md#errorshtml-page)).

## What a refusal tells you [#what-a-refusal-tells-you]

* **A missing grant:** a `403` that a grant could lift names it in `details.grant`, with its `kind` (`type`, `edge_type` or `extension`), its `name`, and the `level` the operation needed, `read` or `write`. That's what the key lacks: [Manage keys](/run/manage-keys#narrow-a-key) says who can give it. A `403` that no grant could lift, such as a write to a `system.*` type through the item operations, names none.
* **Data the credential can't read:** never described. An item of a type the credential can't read answers `404 item_not_found`, exactly as an item that doesn't exist does. A credential learns its reach from [Get an overview](/reference/api/instance/getOverview), and a key from [Get the current API key](/reference/api/api-keys/getCurrentKey). [Access](/build/access) explains why.
* **An item in the bin:** a read or a change answers `404 item_not_found` with `"details": { "trashed": true }` when the credential may read the item's type. Read it with `state=trashed`, or restore it before you change it.
* **An edge rule:** `400 edge_constraint_violation` names the rule in `details.constraint`, such as `duplicate` for a second edge of the type between the same two items, or `cardinality` for a second edge at an end that holds one. A writer that sends an edge again after an uncertain answer can treat `duplicate` as success. A working copy gives the same code before it queues the write ([Write edges in a working copy](/build/edges-in-a-working-copy)).

## Retrying [#retrying]

These codes mean the same request can succeed later:

* `write_contention` (`503`): the write waited the five seconds that `details.budget_ms` names for the store's lock, or a restore is running (`details.reason` is `restore_running`, with a `Retry-After`). Send it again unchanged. A write behind a bulk page that keeps writing waits for the page instead, so allow for a long page in its timeout.
* `version_conflict` (`409`): the item changed since the version the write named. Merge your change into the item in `current`, then send it again naming that item's version.
* `idempotency_key_in_flight` (`409`): the first request with this `Idempotency-Key` hasn't answered yet. Send it again with the same key.
* `rate_limited` (`429`): past a limit for the current window. Wait the seconds that `Retry-After` and `details.retry_after_seconds` name.
* `housekeeping_job_running` (`409`): the job is in the middle of a run. Run it again once that run ends.
* `stream_capacity_exhausted` (`503`): the instance is serving as many live event streams as it allows. Open the stream again later.
* `blob_store_unavailable` (`503`): a blob store failed or didn't answer in time. Nothing was written.
* `too_many_connections` (`503`): the instance, or your address, holds as many open connections as it allows.
* `inbound_unavailable` (`503`): an inbound endpoint can't take a delivery now. The sender sends it again after `Retry-After`.
* `insufficient_storage` (`507`): the volume has no room. Send it again once the volume has room, after reading what it changed if `details.write_outcome` is `unknown`.

With `Idempotency-Key`, a retried write is safe: Marfa answers a repeat with the first answer and doesn't write again. Without one, read what the first request changed before you send a write again.

`500 internal_error` is a fault in the server, and the answer says nothing of what failed. Read what the request changed before you retry, and quote its `X-Request-ID` when you [ask for help](/get-help).

## Codes [#codes]

Every code Marfa answers in the `error` object, by status. The list comes from the [errors chapter of the contract](https://github.com/withmarfa/marfa/blob/main/conformance/spec/errors.md), which is written from the server's own list of codes.

| Code | Status | Meaning |
| - | - | - |
| `bulk_cap_exceeded` | 400 | A bulk action matched more items than its `max_items` allows. |
| `bulk_confirmation_required` | 400 | A destructive bulk action was sent without its confirmation literal. |
| `edge_constraint_violation` | 400 | An edge write breaks a constraint of its edge type or of the link graph, such as cardinality, endpoint types or a duplicate. |
| `edge_cycle` | 400 | An edge would close a cycle: a self-loop on any edge type, a loop on an edge type that must stay acyclic, or a chain of `with-hosts` edges that would make an item a part of its own part. |
| `inheritance_violation` | 400 | A type changes the shape of a field it inherits, or a change to a parent clashes with a field a child declares. |
| `invalid_client` | 400 | The device sign-in page names a client that is not registered. |
| `invalid_id` | 400 | An item, edge or folder id is not a well-formed identifier. |
| `invalid_properties` | 400 | An item's properties break the schema of its type, or an edge's break the property schema of its edge type, including the `path` of an `in-folder` edge. |
| `invalid_schema` | 400 | A type or edge type carries a schema the server cannot accept. |
| `invalid_transition` | 400 | The move is not one the current state of the item or folder allows. |
| `missing_required_field` | 400 | A field the operation requires is absent. `details.field` names it. |
| `property_shadows_field` | 400 | A type declares a field with the name of a first-class item field. |
| `unknown_type` | 400 | A well-formed type identifier names a type nobody registered. |
| `validation_error` | 400 | The request is malformed or breaks a rule that no other code names, such as a bad body, parameter, cursor or limit. |
| `insufficient_user_authentication` | 401 | An app's owner signed in longer ago than an act allows. `details.max_age` gives the seconds allowed; sign the owner in again with `max_age`. |
| `setup_proof_invalid` | 401 | The setup code, handoff link or setup session is wrong, spent, expired or replaced. Ask for a new setup code or link. |
| `unauthorized` | 401 | The request carries no credential the server accepts: none, an unknown or revoked one, or an expired or altered link. |
| `app_sign_in_required` | 403 | An API key asks for an act only a person signed in to an app, or the private local command, may make. |
| `core_type_immutable` | 403 | The type ships with the platform, so it cannot be replaced, deleted or moved out of. |
| `edge_type_not_permitted` | 403 | The credential lacks the edge-type permission the operation needs. |
| `forbidden` | 403 | The credential is valid but lacks a standing permission, reach or origin the operation needs. |
| `type_not_permitted` | 403 | The credential holds no grant on the type at the level the operation asks for. |
| `backup_not_found` | 404 | The backup destination holds no backup by this name from this instance id. |
| `batch_not_found` | 404 | The change log of the item's table holds no batch with this id: it belongs to another table, never existed or is older than `row_log_retention_days`. |
| `blob_copy_not_found` | 404 | The named store holds no copy of the blob, or is not attached. |
| `blob_not_found` | 404 | No blob the caller may read has this hash, or no attached store holds its bytes. On a write of a file item, no blob the caller uploaded or may read has the hash its `blob_ref` names. |
| `bulk_job_not_found` | 404 | No bulk action job the caller can see has this id. |
| `connector_not_found` | 404 | No connector registration the credential may read has this id. |
| `delivery_not_found` | 404 | The connector's registration has no delivery with this id. |
| `edge_not_found` | 404 | No edge the caller may read has this id. |
| `edge_type_not_found` | 404 | No edge type is registered under this identifier. |
| `endpoint_not_found` | 404 | The connector's registration has no endpoint with this id. |
| `grant_not_found` | 404 | No app grant has this id. |
| `housekeeping_job_not_found` | 404 | The instance runs no housekeeping job of this name, or has switched it off. |
| `item_not_found` | 404 | No item the caller may read has this id: it does not exist, is in the bin, or is of a type the caller may not read. |
| `key_not_found` | 404 | No key the caller can reach has this id, or the key was already revoked. |
| `not_found` | 404 | The request names a path or address the server does not serve. |
| `owner_not_found` | 404 | The instance has no owner yet. |
| `passkey_not_found` | 404 | No passkey of the owner has this id. |
| `row_not_found` | 404 | The item's table holds no row with this id. |
| `sign_in_not_found` | 404 | No live sign-in of the owner has this id: it never existed, has ended or has expired. |
| `source_not_found` | 404 | The caller can't see a source with this code. |
| `table_not_found` | 404 | The item's type declares no table of this name. |
| `type_not_found` | 404 | No registered type has this identifier. |
| `webhook_not_found` | 404 | No webhook subscription the caller can reach has this id. |
| `request_timeout` | 408 | A body did not arrive in time: a body read whole was not whole by its deadline, or a delivery, a restore, a blob upload or an avatar received no bytes for its idle limit. |
| `ancestor_unavailable` | 409 | The write names a version that has no snapshot the caller may merge against. |
| `backup_files_missing` | 409 | A restore of a backup names files that neither the backup destination nor the instance holds whole, and that the backup does not record as lost. Nothing is restored. `details.missing_blobs` names them. |
| `backup_parts_missing` | 409 | A restore of a backup names parts that are missing where backups go, or whose size or SHA-256 differs from what the backup recorded. Nothing is restored. `details.missing_parts` names them. |
| `conflict` | 409 | The request collides with the current state in a way that no other code names. |
| `connector_held` | 409 | Another process holds the connector's registration until `details.expires_at`. |
| `copies_below_minimum` | 409 | Dropping the copy would leave fewer live copies than the instance's minimum. |
| `copy_held_by_backup` | 409 | A backup kept where the named store holds the files of backups names the blob. |
| `edge_type_in_use` | 409 | Edges of the edge type still exist, and the delete did not ask to force. |
| `enforcement_unreadable` | 409 | An archive export was asked for while the instance's stored enforcement settings do not read. No archive bytes were sent. Set the settings again, then export again. |
| `export_entry_unrestorable` | 409 | An archive export selected an item or edge that a restore would refuse or skip, or whose line is longer than a restore reads. No archive bytes were sent. `details.entry` names it. |
| `housekeeping_job_running` | 409 | The housekeeping job is in the middle of a run. |
| `id_reused` | 409 | A caller-minted id already names a different item or edge, or an item the caller cannot read. |
| `idempotency_key_in_flight` | 409 | An `Idempotency-Key` is held by another request, or kept changing hands. Retry. |
| `instance_changed` | 409 | A request names another instance in `X-Marfa-Instance-Id`. Nothing is written. Rebuild the working copy from the instance at this address. |
| `item_exists` | 409 | A create that asked not to overwrite names a source and source id, or an id, that an item already holds. Nothing is written. `details.existing_id` names the item. |
| `link_taken` | 409 | A write would give an item a link that another item of its type holds. |
| `no_backup_destination` | 409 | The instance has nowhere to put backups: neither `backup_path` nor `object_store_bucket` is set, so it keeps none. |
| `owner_exists` | 409 | The instance already has an owner. |
| `reach_changed` | 409 | A conditional copy read or copy stream carries a proof for a reach that has since changed. Rebuild the working copy. |
| `sign_in_address_change_unconfirmed` | 409 | A write moves the sign-in address without `confirm_sign_in_address_change`. Nothing is changed; `details.consequences` names what the move would do. |
| `sign_in_address_check_failed` | 409 | A write moves the sign-in address to one that does not answer as this instance. Nothing is changed; `details.reason` says why: `unreachable`, `timed_out` or `not_this_instance`. |
| `source_id_conflict` | 409 | A change to `source_id` names a natural key that another item already holds under the same source. |
| `trash_plan_changed` | 409 | A trash names a `digest` that no longer matches what it would move to the trash. Nothing is trashed; preview it again. |
| `type_chain_unresolvable` | 409 | The stored definition of a type does not read. `PUT /types/{id}` still accepts a corrected schema. |
| `type_exists` | 409 | A type is already registered under this identifier. |
| `type_has_subtypes` | 409 | Another type declares this type as its parent. Forcing the delete does not override this. |
| `type_in_use` | 409 | Items of the type still exist, the bin included, or a folder, view, webhook setting or table column names it, or rows hold a table or column a replacement removes, and the request did not ask to force. |
| `type_mismatch` | 409 | The request declares a type other than the type of the item it resolved. |
| `type_move_blocked` | 409 | A folder, view or webhook setting names the type, and the move can't rewrite it, or an item holds rows in a table the target type does not declare. `details` names each. |
| `undo_conflict` | 409 | A row the batch changed has been changed by a later batch, so an undo would drop that work. `details.rows` names the rows. |
| `update_not_ready` | 409 | No release newer than the running one has been found, or the release check is off. |
| `update_unavailable` | 409 | The server cannot update itself, so `POST /update` changed nothing. `details.step` says what to do on its host. |
| `version_conflict` | 409 | The write names a version that is no longer the current one. The answer carries the current state. |
| `contract_mismatch` | 412 | A request names another contract version in `X-Marfa-Contract` than the server speaks, or names a value that is not a whole number. Nothing is done. Build the client for the version the server speaks. |
| `request_too_large` | 413 | The request body is over the cap for its operation. |
| `range_not_satisfiable` | 416 | A `Range` request asks for bytes the blob does not have. `Content-Range` names its size. |
| `compatible_with_violation` | 422 | A `compatible_with` claim is invalid, or a change breaks another type's claim. `details.dependent_type_ids` names dependents whose claims the change would break. |
| `idempotency_contract_changed` | 422 | An `Idempotency-Key` repeats a request whose first answer was made under another contract version. `details.original_status` is the status it carried. |
| `idempotency_key_reused` | 422 | An `Idempotency-Key` is sent with a different request than the one it first named. |
| `idempotency_result_not_retained` | 422 | An `Idempotency-Key` repeats a request whose first answer was too large to keep. `details.original_status` is the status it carried. |
| `rate_limited` | 429 | A credential, an address or an inbound endpoint is past a limit for its current window. `Retry-After` names the wait. |
| `internal_error` | 500 | A fault that nothing else names a refusal for. The answer says nothing of what failed. |
| `blob_store_unavailable` | 503 | A blob store failed, or did not answer in time, while Marfa checked, read, wrote or deleted a blob's copy. Nothing was written. Retry later. |
| `inbound_unavailable` | 503 | An inbound endpoint cannot take a delivery now, because its connector's backlog is full or the instance holds as many bodies in flight as it allows. Retry later. |
| `stream_capacity_exhausted` | 503 | The instance is serving as many live event streams as it allows. `details.reason` is `viewer_cap`. |
| `too_many_connections` | 503 | The public listener holds as many open connections as it allows, or the caller's address does. Answered before any request is read; retry later. |
| `write_contention` | 503 | A write could not get the store's write lock within the busy budget, or a restore is running (`details.reason` `restore_running`). Retry it unchanged. |
| `insufficient_storage` | 507 | The volume the instance writes to has no room for the request, or the request would leave less free than the instance's reserve. Nothing was kept unless `details.write_outcome` is `unknown`. |
| `bulk_atomic_rollback` | The inner refusal's | An atomic bulk page failed on one entry, so nothing was written. `details` names the entry and the refusal. |
