Error codes
MarkdownEvery 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
| Code | Status | remediation.action | Meaning |
|---|---|---|---|
validation_error | 400 / 422 | fix_request | The request is invalid. |
invalid_request | 400 / 422 | fix_request | The request is invalid. |
unsupported_contract_version | 400 | drop_contract_version | The service does not support this Mirabase-Contract-Version value: drop the header. |
unauthorized | 401 | check_api_key | The key is missing, invalid, expired, or revoked. |
account_pending_approval | 403 | wait_for_approval | The account has not been approved yet. Retry after approval, with the same key. |
account_rejected | 403 | contact_support | The account was not approved. Reach out through the contact page. |
account_suspended | 403 | contact_support | The account is suspended. Reach out through the contact page. |
forbidden | 403 | check_permissions | Capability or role is insufficient. |
identity_override | 403 | remove_identity_fields | The request sent a server-controlled field such as principal_id. |
proposal_required | 403 | request_direct_write_mode | An Agent changed someone else's file and needs write_mode: direct. |
reserved_path | 403 | choose_another_path | The path is under /.mirabase/. |
outside_write_root | 403 | ask_owner_to_change_write_root | The write lands outside the member's write root. |
outside_read_root | 403 | ask_owner_to_change_read_root | A member with a read root used a branch. |
outside_metadata_scope | 403 | omit_scope_metadata_keys | A 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_unavailable | 403 | use_unscoped_key | A key with a metadata scope can only read, search, answer, and ingest: this operation needs a key without a scope. |
console_session_required | 403 | use_console | This operation accepts a console session only, not an API key: do it in the console. |
not_found | 404 | check_identifier | Missing or not visible to you. |
content_not_ready | 404 | wait_and_retry | This view waits for processing. |
branch_not_found | 404 | check_identifier | The branch does not exist. |
checkpoint_not_found | 404 | check_identifier | The checkpoint does not exist. |
object_not_found | 404 | check_identifier | The branch object does not exist. |
snapshot_not_found | 404 | check_identifier | The snapshot does not exist. |
webhook_not_found | 404 | check_identifier | The webhook does not exist. |
upload_not_found | 404 | check_identifier | The upload does not exist. |
virtual_file | 405 | use_memories_api | /.mirabase/memory/MEMORY.md and RECENT.md are read-only views. |
request_timeout | 408 | retry_later | Reading the request body timed out. |
conflict | 409 | - | 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_conflict | 409 | choose_another_path | The target path is occupied. |
not_a_directory | 409 | choose_another_path | A segment of the path is a file. |
move_into_descendant | 409 | choose_another_path | A directory cannot move into itself. |
copy_into_descendant | 409 | choose_another_path | A directory cannot be copied into itself. |
directory_not_empty | 409 | set_recursive | Deleting a non-empty directory needs recursive: true. |
subtree_too_large | 409 | split_request | Over the synchronous node limit: split the request, or send Prefer: respond-async. |
directory_is_write_root | 409 | change_member_write_root | The directory is, or contains, a member's write root. |
directory_is_read_root | 409 | change_member_read_root | The directory is, or contains, a member's read root. |
content_url_unavailable | 409 | use_content_endpoint | A small text file kept on the server has no URL: read it with view=raw. |
too_many_open_proposals | 409 | review_or_withdraw_proposals | The Agent already has 100 open proposals in the Space. |
proposal_conflict | 409 | resubmit_proposal | The file changed or went to the trash since the proposal: submit a new one. |
proposal_closed | 409 | stop_retrying | The proposal or memory proposal is no longer open. |
memory_pending_review | 409 | review_memory_first | The memory is waiting for review: review it before changing it. |
memory_already_reviewed | 409 | stop_retrying | The memory is no longer pending review. |
memory_superseded | 409 | read_current_memory | The memory was replaced by a later revision: read the current one. |
undo_window_expired | 409 | stop_retrying | Undo is available for 30 minutes only. |
undo_not_applicable | 409 | undo_the_correction | A distilled fact has no write to undo: undo the correction that replaced it. |
upload_not_open | 409 | start_new_upload | The upload is completed or aborted: start a new one. |
upload_conflict | 409 | start_new_upload | The upload is in a conflicting state: start a new one. |
snapshot_name_taken | 409 | choose_another_name | The Space already has a snapshot with this name. |
too_many_snapshots | 409 | delete_unused_snapshots | The Space has its maximum of snapshots. |
snapshot_too_large | 409 | review_usage | Over the snapshot's file limit. |
too_many_webhooks | 409 | delete_unused_webhooks | The Space has its maximum of webhooks. |
export_too_large | 409 | split_request | The export is over the file or byte limit: export a path at a time. |
artifact_not_ready | 409 | wait_for_job | The export has not finished. |
space_busy | 409 | wait_and_retry | The Space stayed busy for 2 seconds. Retry-After: 1 second. |
space_external_id_taken | 409 | find_space_by_external_id | Another 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_flight | 409 | wait_and_retry | Work is in flight: wait for job_id. |
evidence_changed | 409 | retry_request | The evidence changed while the result was built: send it again. |
branch_not_active | 409 | open_new_branch | The branch is merged or abandoned. |
branch_name_taken | 409 | choose_another_name | An active branch already has this name. |
branch_limit_reached | 409 | abandon_or_merge_branches | The Space has its maximum of active branches. |
branch_too_large | 409 | merge_or_split_branch | The branch has its maximum of paths. |
checkpoint_limit_reached | 409 | open_new_branch | The branch has its maximum of checkpoints. |
merge_conflict | 409 | resolve_conflicts | Main changed paths the branch also changed: see conflicts. |
merge_too_large | 409 | split_request | Over 1000 paths in one merge: split it with paths, or send Prefer: respond-async. |
merge_in_progress | 409 | wait_for_job | A merge job of this branch is queued or running. |
dream_run_in_flight | 409 | wait_for_job | A dream of this scope is queued or running. |
dreaming_disabled | 409 | enable_memory_dreaming | The Space's consolidation setting is off. |
api_key_not_live | 409 | issue_new_key | The key is revoked or expired. |
self_rotation_not_allowed | 409 | issue_new_key_then_revoke | A key cannot rotate itself. |
owner_membership_immutable | 409 | keep_owner_membership | The owner's membership cannot change. |
default_space_protected | 409 | keep_default_space | The default Space cannot be deleted. |
tenant_deleted | 409 | stop_requests | The account was deleted. |
tenant_limit_reached | 409 | delete_unused_resources | The account has its maximum of live keys, principals, or Spaces. |
gone | 410 | stop_retrying | The Entry behind this receipt was erased. |
cursor_expired | 410 | resync_from_tree | The cursor is over 90 days old: resync from tree. |
artifact_expired | 410 | start_new_export | The export failed, is over 7 days old, or was invalidated by a purge or a read-root change. |
export_invalidated | 410 | start_new_export | Content was erased or the read scope changed during the export: start a new one. |
precondition_failed | 412 | reread_and_retry | If-Match or If-None-Match failed. |
payload_too_large | 413 | reduce_payload | The request body is too large. |
patch_base_too_large | 413 | use_put | The file is over 1 MiB, too large for PATCH. |
archive_too_large | 413 | split_archive | The import archive is too large or has over 10,000 members. |
upload_invalid | 413 / 422 | fix_request | The upload request is invalid, or the file is over the limit. |
upload_media_type_mismatch | 415 | fix_request | The uploaded content type differs from the one declared at the start. |
unsupported_media_type | 415 | use_put | Not UTF-8 text. |
range_not_satisfiable | 416 | fix_request | The Range lies outside the file. |
invalid_path | 422 | fix_path | The path breaks the rules. |
path_too_long | 422 | shorten_path | The path is over the limit. |
edit_no_match | 422 | reread_and_retry | old_text was not found. |
edit_ambiguous | 422 | add_context_or_replace_all | old_text appears more than once. |
view_not_available | 422 | choose_another_view | This source has no such view. |
upload_expired | 422 | start_new_upload | The upload session has ended. |
upload_size_mismatch | 422 | fix_request | The uploaded bytes differ from the size declared at the start. |
upload_integrity_mismatch | 422 | start_new_upload | The uploaded content does not match checksum_sha256: upload again. |
checksum_mismatch | 422 | fix_request | A branch object does not hash to its sha256. |
unknown_citation | 422 | use_citations_from_pack | A citation in the feedback is not in the pack. |
write_root_outside_read_root | 422 | set_write_root_inside_read_root | The write root is not inside the read root. |
invalid_webhook_url | 422 | fix_webhook_url | The webhook URL is not public https on port 443. |
unsupported_archive | 422 | use_tar_archive | The import is not a tar or gzip-compressed tar. |
rate_limited | 429 | wait_and_retry | Request 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_waiters | 429 | wait_and_retry | A key already holds 4 long polls. Retry-After: 1 second. |
ingest_backlog | 429 | wait_and_retry | Too 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_jobs | 429 | wait_and_retry | The Space already runs 4 jobs that change the tree, or 4 exports. Retry-After: 30 seconds. |
login_code_throttled | 429 | wait_and_retry | Console 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_exceeded | 429 | review_usage | A 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_error | 500 | retry_later | An internal error. |
model_failed | 502 | retry_later | The model call failed while answering. |
original_unavailable | 503 | retry_later | The original is temporarily unavailable. |
answer_unavailable | 503 | retry_later | The answer model is temporarily unavailable. |
object_store_unavailable | 503 | retry_later | Object storage is temporarily unavailable. |
object_store_request_failed | 503 | retry_later | Object storage is temporarily unavailable. |
object_stream_integrity_mismatch | 503 | retry_later | Object storage is temporarily unavailable. |
spec_unavailable | 503 | feature_not_enabled | This deployment does not have the feature enabled, and retrying does not help. |
webhooks_unavailable | 503 | feature_not_enabled | This deployment does not have the feature enabled, and retrying does not help. |
answer_not_configured | 503 | use_context_with_your_model | This deployment has no answer model: build a context pack with POST /v2/retrieval/context and run your own model. |
deadline_exceeded | 504 | retry_later | Retrieval ran past the deadline_ms in the request. |
Next steps
- API conventions: the error envelope, retries, and rate limits.
- SDK: the error classes the SDKs throw.
- API reference: the statuses each endpoint can return.
