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:
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
HEADrequest gets the status and headers with no body. 409 version_conflictand409 ancestor_unavailablealso carry the item as it is now, incurrentbesideerror, 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
Acceptnamestext/htmlbeforeapplication/jsongets an HTML page of the refusal's status, still withX-Error-Code(errors/html-page).
What a refusal tells you
- A missing grant: a
403that a grant could lift names it indetails.grant, with itskind(type,edge_typeorextension), itsname, and thelevelthe operation needed,readorwrite. That's what the key lacks: Manage keys says who can give it. A403that no grant could lift, such as a write to asystem.*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_foundwith"details": { "trashed": true }when the credential may read the item's type. Read it withstate=trashed, or restore it before you change it. - An edge rule:
400 edge_constraint_violationnames the rule indetails.constraint, such asduplicatefor a second edge of the type between the same two items, orcardinalityfor a second edge at an end that holds one. A writer that sends an edge again after an uncertain answer can treatduplicateas 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 thatdetails.budget_msnames for the store's lock, or a restore is running (details.reasonisrestore_running, with aRetry-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 incurrent, then send it again naming that item's version.idempotency_key_in_flight(409): the first request with thisIdempotency-Keyhasn't answered yet. Send it again with the same key.rate_limited(429): past a limit for the current window. Wait the seconds thatRetry-Afteranddetails.retry_after_secondsname.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 afterRetry-After.insufficient_storage(507): the volume has no room. Send it again once the volume has room, after reading what it changed ifdetails.write_outcomeisunknown.
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_itemsallows. 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-hostsedges 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
pathof anin-folderedge. 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.fieldnames 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_agegives the seconds allowed; sign the owner in again withmax_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_refnames. 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_blobsnames 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_partsnames 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.entrynames 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-Keyis 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_idnames 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_pathnorobject_store_bucketis 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.consequencesnames 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.reasonsays why:unreachable,timed_outornot_this_instance. source_id_conflict- Status 409
- A change to
source_idnames a natural key that another item already holds under the same source. trash_plan_changed- Status 409
- A trash names a
digestthat 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.
detailsnames 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.rowsnames 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 /updatechanged nothing.details.stepsays 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-Contractthan 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
Rangerequest asks for bytes the blob does not have.Content-Rangenames its size. compatible_with_violation- Status 422
- A
compatible_withclaim is invalid, or a change breaks another type's claim.details.dependent_type_idsnames dependents whose claims the change would break. idempotency_contract_changed- Status 422
- An
Idempotency-Keyrepeats a request whose first answer was made under another contract version.details.original_statusis the status it carried. idempotency_key_reused- Status 422
- An
Idempotency-Keyis sent with a different request than the one it first named. idempotency_result_not_retained- Status 422
- An
Idempotency-Keyrepeats a request whose first answer was too large to keep.details.original_statusis 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-Afternames 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.reasonisviewer_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.reasonrestore_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_outcomeisunknown. bulk_atomic_rollback- Status The inner refusal's
- An atomic bulk page failed on one entry, so nothing was written.
detailsnames the entry and the refusal.