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 answers the same codes.

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:

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. 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 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).
  • 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).

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 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, and a key from Get the current API key. 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).

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.

Codes

Every code Marfa answers in the error object, by status. The list comes from the errors chapter of the contract, which is written from the server's own list of codes.

bulk_cap_exceeded
Status 400
A bulk action matched more items than its max_items allows.
bulk_confirmation_required
Status 400
A destructive bulk action was sent without its confirmation literal.
edge_constraint_violation
Status 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
Status 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
Status 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
Status 400
The device sign-in page names a client that is not registered.
invalid_id
Status 400
An item, edge or folder id is not a well-formed identifier.
invalid_properties
Status 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
Status 400
A type or edge type carries a schema the server cannot accept.
invalid_transition
Status 400
The move is not one the current state of the item or folder allows.
missing_required_field
Status 400
A field the operation requires is absent. details.field names it.
property_shadows_field
Status 400
A type declares a field with the name of a first-class item field.
unknown_type
Status 400
A well-formed type identifier names a type nobody registered.
validation_error
Status 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
Status 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
Status 401
The setup code, handoff link or setup session is wrong, spent, expired or replaced. Ask for a new setup code or link.
unauthorized
Status 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
Status 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
Status 403
The type ships with the platform, so it cannot be replaced, deleted or moved out of.
edge_type_not_permitted
Status 403
The credential lacks the edge-type permission the operation needs.
forbidden
Status 403
The credential is valid but lacks a standing permission, reach or origin the operation needs.
type_not_permitted
Status 403
The credential holds no grant on the type at the level the operation asks for.
backup_not_found
Status 404
The backup destination holds no backup by this name from this instance id.
batch_not_found
Status 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
Status 404
The named store holds no copy of the blob, or is not attached.
blob_not_found
Status 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
Status 404
No bulk action job the caller can see has this id.
connector_not_found
Status 404
No connector registration the credential may read has this id.
delivery_not_found
Status 404
The connector's registration has no delivery with this id.
edge_not_found
Status 404
No edge the caller may read has this id.
edge_type_not_found
Status 404
No edge type is registered under this identifier.
endpoint_not_found
Status 404
The connector's registration has no endpoint with this id.
grant_not_found
Status 404
No app grant has this id.
housekeeping_job_not_found
Status 404
The instance runs no housekeeping job of this name, or has switched it off.
item_not_found
Status 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
Status 404
No key the caller can reach has this id, or the key was already revoked.
not_found
Status 404
The request names a path or address the server does not serve.
owner_not_found
Status 404
The instance has no owner yet.
passkey_not_found
Status 404
No passkey of the owner has this id.
row_not_found
Status 404
The item's table holds no row with this id.
sign_in_not_found
Status 404
No live sign-in of the owner has this id: it never existed, has ended or has expired.
source_not_found
Status 404
The caller can't see a source with this code.
table_not_found
Status 404
The item's type declares no table of this name.
type_not_found
Status 404
No registered type has this identifier.
webhook_not_found
Status 404
No webhook subscription the caller can reach has this id.
request_timeout
Status 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
Status 409
The write names a version that has no snapshot the caller may merge against.
backup_files_missing
Status 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
Status 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
Status 409
The request collides with the current state in a way that no other code names.
connector_held
Status 409
Another process holds the connector's registration until details.expires_at.
copies_below_minimum
Status 409
Dropping the copy would leave fewer live copies than the instance's minimum.
copy_held_by_backup
Status 409
A backup kept where the named store holds the files of backups names the blob.
edge_type_in_use
Status 409
Edges of the edge type still exist, and the delete did not ask to force.
enforcement_unreadable
Status 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
Status 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
Status 409
The housekeeping job is in the middle of a run.
id_reused
Status 409
A caller-minted id already names a different item or edge, or an item the caller cannot read.
idempotency_key_in_flight
Status 409
An Idempotency-Key is held by another request, or kept changing hands. Retry.
instance_changed
Status 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
Status 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
Status 409
A write would give an item a link that another item of its type holds.
no_backup_destination
Status 409
The instance has nowhere to put backups: neither backup_path nor object_store_bucket is set, so it keeps none.
owner_exists
Status 409
The instance already has an owner.
reach_changed
Status 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
Status 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
Status 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
Status 409
A change to source_id names a natural key that another item already holds under the same source.
trash_plan_changed
Status 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
Status 409
The stored definition of a type does not read. PUT /types/{id} still accepts a corrected schema.
type_exists
Status 409
A type is already registered under this identifier.
type_has_subtypes
Status 409
Another type declares this type as its parent. Forcing the delete does not override this.
type_in_use
Status 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
Status 409
The request declares a type other than the type of the item it resolved.
type_move_blocked
Status 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
Status 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
Status 409
No release newer than the running one has been found, or the release check is off.
update_unavailable
Status 409
The server cannot update itself, so POST /update changed nothing. details.step says what to do on its host.
version_conflict
Status 409
The write names a version that is no longer the current one. The answer carries the current state.
contract_mismatch
Status 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
Status 413
The request body is over the cap for its operation.
range_not_satisfiable
Status 416
A Range request asks for bytes the blob does not have. Content-Range names its size.
compatible_with_violation
Status 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
Status 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
Status 422
An Idempotency-Key is sent with a different request than the one it first named.
idempotency_result_not_retained
Status 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
Status 429
A credential, an address or an inbound endpoint is past a limit for its current window. Retry-After names the wait.
internal_error
Status 500
A fault that nothing else names a refusal for. The answer says nothing of what failed.
blob_store_unavailable
Status 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
Status 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
Status 503
The instance is serving as many live event streams as it allows. details.reason is viewer_cap.
too_many_connections
Status 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
Status 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
Status 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
Status The inner refusal's
An atomic bulk page failed on one entry, so nothing was written. details names the entry and the refusal.

On this page