Skip to content
Developer docs
Docs menu

Error codes

Markdown

Every error code an API key can receive, with its HTTP status, remediation.action, meaning, and Retry-After.

This table is generated from the OpenAPI document. The structure of the error envelope, how to retry, and the rate limits are in API conventions. Branch on code and remediation.action. A code without a remediation.action has no fixed next step: handle it by its HTTP status. Future updates may add new codes; handle an unknown code by its HTTP status as well.

Error codes

CodeStatusremediation.actionMeaning
validation_error400 / 422fix_requestThe request is invalid.
invalid_request400 / 422fix_requestThe request is invalid.
unsupported_contract_version400drop_contract_versionThe service does not support this Mirabase-Contract-Version value: drop the header.
unauthorized401check_api_keyThe key is missing, invalid, expired, or revoked.
account_pending_approval403wait_for_approvalThe account has not been approved yet. Retry after approval, with the same key.
account_rejected403contact_supportThe account was not approved. Reach out through the contact page.
account_suspended403contact_supportThe account is suspended. Reach out through the contact page.
forbidden403check_permissionsCapability or role is insufficient.
identity_override403remove_identity_fieldsThe request sent a server-controlled field such as principal_id.
proposal_required403request_direct_write_modeAn Agent changed someone else's file and needs write_mode: direct.
reserved_path403choose_another_pathThe path is under /.mirabase/.
outside_write_root403ask_owner_to_change_write_rootThe write lands outside the member's write root.
outside_read_root403ask_owner_to_change_read_rootA member with a read root used a branch.
outside_metadata_scope403omit_scope_metadata_keysA key with a metadata scope wrote another value under a scope key: leave the key out, or send the scope's first value.
scoped_key_route_unavailable403use_unscoped_keyA key with a metadata scope can only read, search, answer, and ingest: this operation needs a key without a scope.
console_session_required403use_consoleThis operation accepts a console session only, not an API key: do it in the console.
not_found404check_identifierMissing or not visible to you.
content_not_ready404wait_and_retryThis view waits for processing.
branch_not_found404check_identifierThe branch does not exist.
checkpoint_not_found404check_identifierThe checkpoint does not exist.
object_not_found404check_identifierThe branch object does not exist.
snapshot_not_found404check_identifierThe snapshot does not exist.
webhook_not_found404check_identifierThe webhook does not exist.
upload_not_found404check_identifierThe upload does not exist.
virtual_file405use_memories_api/.mirabase/memory/MEMORY.md and RECENT.md are read-only views.
request_timeout408retry_laterReading the request body timed out.
conflict409-The request conflicts with the current state. remediation.action is use_new_idempotency_key only when an Idempotency-Key was reused with different input; other conflicts have no action.
path_conflict409choose_another_pathThe target path is occupied.
not_a_directory409choose_another_pathA segment of the path is a file.
move_into_descendant409choose_another_pathA directory cannot move into itself.
copy_into_descendant409choose_another_pathA directory cannot be copied into itself.
directory_not_empty409set_recursiveDeleting a non-empty directory needs recursive: true.
subtree_too_large409split_requestOver the synchronous node limit: split the request, or send Prefer: respond-async.
directory_is_write_root409change_member_write_rootThe directory is, or contains, a member's write root.
directory_is_read_root409change_member_read_rootThe directory is, or contains, a member's read root.
content_url_unavailable409use_content_endpointA small text file kept on the server has no URL: read it with view=raw.
too_many_open_proposals409review_or_withdraw_proposalsThe Agent already has 100 open proposals in the Space.
proposal_conflict409resubmit_proposalThe file changed or went to the trash since the proposal: submit a new one.
proposal_closed409stop_retryingThe proposal or memory proposal is no longer open.
memory_pending_review409review_memory_firstThe memory is waiting for review: review it before changing it.
memory_already_reviewed409stop_retryingThe memory is no longer pending review.
memory_superseded409read_current_memoryThe memory was replaced by a later revision: read the current one.
undo_window_expired409stop_retryingUndo is available for 30 minutes only.
undo_not_applicable409undo_the_correctionA distilled fact has no write to undo: undo the correction that replaced it.
upload_not_open409start_new_uploadThe upload is completed or aborted: start a new one.
upload_conflict409start_new_uploadThe upload is in a conflicting state: start a new one.
snapshot_name_taken409choose_another_nameThe Space already has a snapshot with this name.
too_many_snapshots409delete_unused_snapshotsThe Space has its maximum of snapshots.
snapshot_too_large409review_usageOver the snapshot's file limit.
too_many_webhooks409delete_unused_webhooksThe Space has its maximum of webhooks.
export_too_large409split_requestThe export is over the file or byte limit: export a path at a time.
artifact_not_ready409wait_for_jobThe export has not finished.
space_busy409wait_and_retryThe Space stayed busy for 2 seconds. Retry-After: 1 second.
space_external_id_taken409find_space_by_external_idAnother Space in the account already has this external_id. If you can see it, get it with GET /v2/spaces?external_id= or PUT /v2/spaces/ext:<external_id>; if you cannot, choose another id.
job_in_flight409wait_and_retryWork is in flight: wait for job_id.
evidence_changed409retry_requestThe evidence changed while the result was built: send it again.
branch_not_active409open_new_branchThe branch is merged or abandoned.
branch_name_taken409choose_another_nameAn active branch already has this name.
branch_limit_reached409abandon_or_merge_branchesThe Space has its maximum of active branches.
branch_too_large409merge_or_split_branchThe branch has its maximum of paths.
checkpoint_limit_reached409open_new_branchThe branch has its maximum of checkpoints.
merge_conflict409resolve_conflictsMain changed paths the branch also changed: see conflicts.
merge_too_large409split_requestOver 1000 paths in one merge: split it with paths, or send Prefer: respond-async.
merge_in_progress409wait_for_jobA merge job of this branch is queued or running.
dream_run_in_flight409wait_for_jobA dream of this scope is queued or running.
dreaming_disabled409enable_memory_dreamingThe Space's consolidation setting is off.
api_key_not_live409issue_new_keyThe key is revoked or expired.
self_rotation_not_allowed409issue_new_key_then_revokeA key cannot rotate itself.
owner_membership_immutable409keep_owner_membershipThe owner's membership cannot change.
default_space_protected409keep_default_spaceThe default Space cannot be deleted.
tenant_deleted409stop_requestsThe account was deleted.
tenant_limit_reached409delete_unused_resourcesThe account has its maximum of live keys, principals, or Spaces.
gone410stop_retryingThe Entry behind this receipt was erased.
cursor_expired410resync_from_treeThe cursor is over 90 days old: resync from tree.
artifact_expired410start_new_exportThe export failed, is over 7 days old, or was invalidated by a purge or a read-root change.
export_invalidated410start_new_exportContent was erased or the read scope changed during the export: start a new one.
precondition_failed412reread_and_retryIf-Match or If-None-Match failed.
payload_too_large413reduce_payloadThe request body is too large.
patch_base_too_large413use_putThe file is over 1 MiB, too large for PATCH.
archive_too_large413split_archiveThe import archive is too large or has over 10,000 members.
upload_invalid413 / 422fix_requestThe upload request is invalid, or the file is over the limit.
upload_media_type_mismatch415fix_requestThe uploaded content type differs from the one declared at the start.
unsupported_media_type415use_putNot UTF-8 text.
range_not_satisfiable416fix_requestThe Range lies outside the file.
invalid_path422fix_pathThe path breaks the rules.
path_too_long422shorten_pathThe path is over the limit.
edit_no_match422reread_and_retryold_text was not found.
edit_ambiguous422add_context_or_replace_allold_text appears more than once.
view_not_available422choose_another_viewThis source has no such view.
upload_expired422start_new_uploadThe upload session has ended.
upload_size_mismatch422fix_requestThe uploaded bytes differ from the size declared at the start.
upload_integrity_mismatch422start_new_uploadThe uploaded content does not match checksum_sha256: upload again.
checksum_mismatch422fix_requestA branch object does not hash to its sha256.
unknown_citation422use_citations_from_packA citation in the feedback is not in the pack.
write_root_outside_read_root422set_write_root_inside_read_rootThe write root is not inside the read root.
invalid_webhook_url422fix_webhook_urlThe webhook URL is not public https on port 443.
unsupported_archive422use_tar_archiveThe import is not a tar or gzip-compressed tar.
rate_limited429wait_and_retryRequest rate or concurrency limit reached. Retry-After: Seconds until the request bucket has room when limit is request_rate; 1 when limit is concurrency.
too_many_waiters429wait_and_retryA key already holds 4 long polls. Retry-After: 1 second.
ingest_backlog429wait_and_retryToo many jobs are queued for the account: jobs that make content searchable past tenant_queued_jobs, or summaries, classification, relations and memories past five times that. queue says how many of that kind, the limit, whether processing is paused, and an estimate of how long the queue needs. A key limited to some Spaces or to metadata is told only that the limit is reached. Retry-After: 30 to 600: the estimated time until the account's queue is below its limit; 600 while processing is paused. 60 for a key limited to some Spaces or to metadata.
too_many_jobs429wait_and_retryThe Space already runs 4 jobs that change the tree, or 4 exports. Retry-After: 30 seconds.
login_code_throttled429wait_and_retryConsole email codes: requested too often, or too many wrong codes from one address. Retry-After: 60 when codes are requested too often; 3600 after too many requests or wrong codes in an hour.
quota_exceeded429review_usageA stored quota is used up, or the call would take more of it than is left, and retrying does not help. quota names it: writes, storage_bytes, model_tokens, or model_spend_micro_usd.
internal_error500retry_laterAn internal error.
model_failed502retry_laterThe model call failed while answering.
original_unavailable503retry_laterThe original is temporarily unavailable.
answer_unavailable503retry_laterThe answer model is temporarily unavailable.
object_store_unavailable503retry_laterObject storage is temporarily unavailable.
object_store_request_failed503retry_laterObject storage is temporarily unavailable.
object_stream_integrity_mismatch503retry_laterObject storage is temporarily unavailable.
spec_unavailable503feature_not_enabledThis deployment does not have the feature enabled, and retrying does not help.
webhooks_unavailable503feature_not_enabledThis deployment does not have the feature enabled, and retrying does not help.
answer_not_configured503use_context_with_your_modelThis deployment has no answer model: build a context pack with POST /v2/retrieval/context and run your own model.
deadline_exceeded504retry_laterRetrieval ran past the deadline_ms in the request.

Next steps