# Error codes

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](https://mirabase.io/developers/conventions.md#errors). 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=`](https://mirabase.io/developers/api/spaces.md#spaces-list) or [`PUT /v2/spaces/ext:<external_id>`](https://mirabase.io/developers/api/spaces.md#spaces-ensure); 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`](https://mirabase.io/developers/api/retrieval.md#retrieval-buildcontext) and run your own model. |
| `deadline_exceeded` | 504 | `retry_later` | Retrieval ran past the `deadline_ms` in the request. |

## Next steps

- [API conventions](https://mirabase.io/developers/conventions.md#errors): the error envelope, retries, and rate limits.
- [SDK](https://mirabase.io/developers/sdks.md#errors): the error classes the SDKs throw.
- [API reference](https://mirabase.io/developers/api.md): the statuses each endpoint can return.
