跳到主要内容
开发者文档
文档目录

错误码

Markdown 版

API Key 可能收到的每个错误码,及其 HTTP 状态码、remediation.action、含义和 Retry-After。

这张表从 OpenAPI 规格生成。错误信封的结构、重试策略和限流规则见 API 约定。按 code 和 remediation.action 分支处理;没有 remediation.action 的错误码没有固定的下一步,按 HTTP 状态码处理。后续可能新增错误码,未知错误码同样按 HTTP 状态码处理。

错误码

错误码状态remediation.action含义
validation_error400 / 422fix_request请求不合法。
invalid_request400 / 422fix_request请求不合法。
unsupported_contract_version400drop_contract_version服务不支持这个 Mirabase-Contract-Version 值:去掉这个请求头。
unauthorized401check_api_keyKey 缺失、无效、已过期或已吊销。
account_pending_approval403wait_for_approval账户尚未通过审批。审批通过后,用原来的 Key 重试。
account_rejected403contact_support账户未通过审批。请通过联系页咨询。
account_suspended403contact_support账户已停用。请通过联系页咨询。
forbidden403check_permissions能力或角色不足。
identity_override403remove_identity_fields请求里出现了 principal_id 这类由服务端控制的字段。
proposal_required403request_direct_write_modeAgent 修改他人的文件,需要 write_mode: direct。
reserved_path403choose_another_path路径在 /.mirabase/ 下。
outside_write_root403ask_owner_to_change_write_root写入落在成员的写入根路径之外。
outside_read_root403ask_owner_to_change_read_root有读取根路径的成员使用了分支。
outside_metadata_scope403omit_scope_metadata_keys带元数据范围的 Key 在范围的键上写了其他值:去掉这个键,或使用范围内的第一个值。
scoped_key_route_unavailable403use_unscoped_key带元数据范围的 Key 只能读取、检索、回答和导入:这个操作需要不带范围的 Key。
console_session_required403use_console这个操作只接受控制台会话,不接受 API Key:请在控制台里完成。
not_found404check_identifier不存在,或对你不可见。
content_not_ready404wait_and_retry这个视图需等待处理完成。
branch_not_found404check_identifier分支不存在。
checkpoint_not_found404check_identifier检查点不存在。
object_not_found404check_identifier分支对象不存在。
snapshot_not_found404check_identifier快照不存在。
webhook_not_found404check_identifierWebhook 不存在。
upload_not_found404check_identifier上传不存在。
virtual_file405use_memories_api/.mirabase/memory/MEMORY.md 和 RECENT.md 是只读视图。
request_timeout408retry_later读取请求体超时。
conflict409-请求与当前状态冲突。只有在 Idempotency-Key 被复用于不同输入时,remediation.action 才是 use_new_idempotency_key;其他冲突没有动作。
path_conflict409choose_another_path目标路径已被占用。
not_a_directory409choose_another_path路径中的某一段是文件。
move_into_descendant409choose_another_path目录不能移动到自身内部。
copy_into_descendant409choose_another_path目录不能复制到自身内部。
directory_not_empty409set_recursive删除非空目录需要 recursive: true。
subtree_too_large409split_request超过同步节点上限:拆分请求,或带 Prefer: respond-async。
directory_is_write_root409change_member_write_root该目录是某个成员的写入根路径,或包含它。
directory_is_read_root409change_member_read_root该目录是某个成员的读取根路径,或包含它。
content_url_unavailable409use_content_endpoint服务端保存的小文本文件没有下载地址:用 view=raw 读取。
too_many_open_proposals409review_or_withdraw_proposals这个 Agent 在该 Space 里已有 100 个打开的提案。
proposal_conflict409resubmit_proposal提交提案后文件已变更或移入废纸篓:请重新提交。
proposal_closed409stop_retrying提案或整理提案已不在打开状态。
memory_pending_review409review_memory_first这条记忆正在等待审核:先审核,再修改。
memory_already_reviewed409stop_retrying这条记忆已不在待审核状态。
memory_superseded409read_current_memory这条记忆已被后来的修订取代:请读取当前的记忆。
undo_window_expired409stop_retrying撤销只在 30 分钟内可用。
undo_not_applicable409undo_the_correction提炼出的事实没有可撤销的写入:撤销取代它的那次更正。
upload_not_open409start_new_upload上传已完成或已中止:请重新发起。
upload_conflict409start_new_upload上传处于冲突状态:请重新发起。
snapshot_name_taken409choose_another_name这个 Space 已有同名快照。
too_many_snapshots409delete_unused_snapshots这个 Space 的快照数量已达上限。
snapshot_too_large409review_usage超过快照的文件数上限。
too_many_webhooks409delete_unused_webhooks这个 Space 的 Webhook 数量已达上限。
export_too_large409split_request导出超过文件数或字节上限:按 path 分次导出。
artifact_not_ready409wait_for_job导出尚未完成。
space_busy409wait_and_retry这个 Space 持续繁忙了 2 秒。Retry-After:1 秒。
space_external_id_taken409find_space_by_external_id账户里的另一个 Space 已使用这个 external_id。如果你能看到它,用 GET /v2/spaces?external_id= 或 PUT /v2/spaces/ext:<external_id> 获取;如果看不到,请换一个 id。
job_in_flight409wait_and_retry有工作正在进行:等待 job_id。
evidence_changed409retry_request构建结果期间证据发生了变化:请重新发送。
branch_not_active409open_new_branch分支已合并或已放弃。
branch_name_taken409choose_another_name已有同名的活跃分支。
branch_limit_reached409abandon_or_merge_branches这个 Space 的活跃分支数量已达上限。
branch_too_large409merge_or_split_branch分支的路径数量已达上限。
checkpoint_limit_reached409open_new_branch分支的检查点数量已达上限。
merge_conflict409resolve_conflicts主线修改了分支也修改过的路径:见 conflicts。
merge_too_large409split_request一次合并超过 1000 个路径:用 paths 分批,或带 Prefer: respond-async。
merge_in_progress409wait_for_job这个分支的合并任务正在排队或运行。
dream_run_in_flight409wait_for_job这个范围的一次整理正在排队或运行。
dreaming_disabled409enable_memory_dreaming这个 Space 的整理设置为 off。
api_key_not_live409issue_new_keyKey 已吊销或已过期。
self_rotation_not_allowed409issue_new_key_then_revokeKey 不能轮换自己。
owner_membership_immutable409keep_owner_membership所有者的成员关系不能修改。
default_space_protected409keep_default_space默认 Space 不能删除。
tenant_deleted409stop_requests账户已删除。
tenant_limit_reached409delete_unused_resources账户的活跃 Key、主体或 Space 数量已达上限。
gone410stop_retrying这张回执对应的 Entry 已被彻底删除。
cursor_expired410resync_from_tree游标已超过 90 天:从 tree 重新同步。
artifact_expired410start_new_export导出失败、已超过 7 天,或因彻底删除或读取根路径变化而失效。
export_invalidated410start_new_export导出期间有内容被彻底删除,或读取范围发生了变化:请重新导出。
precondition_failed412reread_and_retryIf-Match 或 If-None-Match 不满足。
payload_too_large413reduce_payload请求体过大。
patch_base_too_large413use_put文件超过 1 MiB,不能用 PATCH。
archive_too_large413split_archive导入的归档过大,或包含超过 10,000 个条目。
upload_invalid413 / 422fix_request上传请求不合法,或文件超过上限。
upload_media_type_mismatch415fix_request上传内容的类型与发起时声明的不一致。
unsupported_media_type415use_put不是 UTF-8 文本。
range_not_satisfiable416fix_requestRange 超出文件范围。
invalid_path422fix_path路径不符合规则。
path_too_long422shorten_path路径超过长度上限。
edit_no_match422reread_and_retry找不到 old_text。
edit_ambiguous422add_context_or_replace_allold_text 出现了不止一次。
view_not_available422choose_another_view这个来源没有这种视图。
upload_expired422start_new_upload上传会话已结束。
upload_size_mismatch422fix_request上传的字节数与发起时声明的 size 不一致。
upload_integrity_mismatch422start_new_upload上传的内容与 checksum_sha256 不符:请重新上传。
checksum_mismatch422fix_request分支对象的哈希与它的 sha256 不符。
unknown_citation422use_citations_from_pack反馈里的某个引用不在这个上下文包里。
write_root_outside_read_root422set_write_root_inside_read_root写入根路径不在读取根路径之内。
invalid_webhook_url422fix_webhook_urlWebhook 地址不是 443 端口上的公网 https 地址。
unsupported_archive422use_tar_archive导入的不是 tar 或 gzip 压缩的 tar。
rate_limited429wait_and_retry达到请求速率或并发上限。Retry-After:limit 为 request_rate 时,是请求令牌桶腾出空间所需的秒数;limit 为 concurrency 时为 1。
too_many_waiters429wait_and_retry一个 Key 已保持 4 个长轮询。Retry-After:1 秒。
ingest_backlog429wait_and_retry账户的排队任务过多:使内容可检索的任务超过 tenant_queued_jobs,或摘要、分类、关联和记忆任务超过它的五倍。queue 给出该类任务的数量、上限、处理是否已暂停,以及队列预计所需的时间。限定了部分 Space 或元数据范围的 Key 只会被告知已达上限。Retry-After:30 到 600:账户队列降到上限以下的预计时间;处理暂停期间为 600。对限定了部分 Space 或元数据范围的 Key 为 60。
too_many_jobs429wait_and_retry这个 Space 已在运行 4 个改动目录树的任务,或 4 个导出。Retry-After:30 秒。
login_code_throttled429wait_and_retry控制台邮箱验证码:请求过于频繁,或同一地址的错误验证码过多。Retry-After:验证码请求过于频繁时为 60;一小时内请求或错误验证码过多时为 3600。
quota_exceeded429review_usage持久配额已用尽,或本次调用所需的量超过剩余额度,重试无效。quota 指明是哪一项:writes、storage_bytes、model_tokens 或 model_spend_micro_usd。
internal_error500retry_later服务内部错误。
model_failed502retry_later回答时模型调用失败。
original_unavailable503retry_later原件暂时不可用。
answer_unavailable503retry_later回答模型暂时不可用。
object_store_unavailable503retry_later对象存储暂时不可用。
object_store_request_failed503retry_later对象存储暂时不可用。
object_stream_integrity_mismatch503retry_later对象存储暂时不可用。
spec_unavailable503feature_not_enabled这个部署没有启用该功能,重试无效。
webhooks_unavailable503feature_not_enabled这个部署没有启用该功能,重试无效。
answer_not_configured503use_context_with_your_model这个部署没有配置回答模型:用 POST /v2/retrieval/context 构建上下文包,交给你自己的模型。
deadline_exceeded504retry_later检索超过了请求里的 deadline_ms。

下一步

  • API 约定:错误信封、重试和限流。
  • SDK:SDK 抛出的错误类型。
  • API 参考:每个接口可能返回的状态码。