错误代码

Fetch Hive API 错误包含人类可读的 message、一个稳定的 error_code，以及作为同一消息兼容别名的 error 字段。较旧的套餐和速率限制响应可能还会包含 code；请将 code 视为已弃用的别名，并优先读取 error_code。 Fetch Hive 会根据你的账户语言设置返回本地化错误消息。错误代码是稳定的标识符，可在客户端代码中可靠使用。

目录接口

使用 GET /v1/error_codes 获取公共目录。该接口未做鉴权，因为它返回的是静态 API 契约元数据。传入 ?locale=es 可请求西班牙语目录文案；不受支持或不可用的 locale 会回退到英文。

{
  "locale": "en",
  "default_field": "error_code",
  "compatibility_aliases": ["code"],
  "codes": [
    {
      "code": "model_deprecated",
      "status": 422,
      "field": "error_code",
      "message_key": "errors.codes.model_deprecated",
      "message": "The selected model \"%{model}\" is no longer available. Choose a current model and try again.",
      "field_aliases": [],
      "category": "runtime",
      "client_action_key": "errors.client_actions.model_deprecated",
      "client_action": "Choose an active model and retry."
    }
  ]
}

JSON 错误结构

{
  "error": "The selected model \"old-model\" is no longer available. Choose a current model and try again.",
  "message": "The selected model \"old-model\" is no longer available. Choose a current model and try again.",
  "error_code": "model_deprecated"
}

SSE 错误结构

流式接口以 Server-Sent Events 形式发送错误，type: "error"。

{
  "type": "error",
  "error": "Provider request failed",
  "message": "Provider request failed",
  "error_code": "provider_error",
  "error_type": "provider_error",
  "status_code": 502
}

代码列表

代码	字段	状态码	含义	客户端操作
`model_deprecated`	`error_code`	`422`	已保存的提示词、智能体、工作流步骤、部署或回退模型已不再可用。	选择一个有效的模型并重试。
`personal_model_missing_credentials`	`error_code`	`422`	个人模型运行需要尚未连接的提供商凭据。	连接凭据或切换到托管/当前模型。
`personal_model_invalid_credentials`	`error_code`	`422`	提供了提供商凭据，但被提供商拒绝。	重新连接或更换提供商凭据。
`insufficient_hosted_llm_credits`	`error_code`	`402`	工作区的托管 LLM 额度不足以完成此次运行。	添加额度、升级套餐或使用个人提供商密钥。
`account_credit_cap_reached`	`error_code`	`422`	账户已达到通用额度上限。	升级套餐或等待获得更多额度后重试。
`asset_storage_limit_reached`	`error_code`	`402`	工作区已达到资产存储上限。	删除资产或升级工作区套餐。
`vision_not_supported`	`error_code`	`422`	所选模型无法处理图像输入。	选择支持视觉的模型或移除图像输入。
`workflow_step_limit_reached`	`error_code`	`402`	工作流已达到套餐的步骤上限。	移除步骤或升级套餐。
`workspace_limit_reached`	`error_code`	`402`	账户已达到套餐的工作区上限。	删除一个工作区或升级套餐。
`api_rate_limit_exceeded`	`error_code`	`429`	API 密钥已达到每日请求上限。	等待重置后重试或升级套餐。
`guest_limit_exceeded`	`error_code`	`429`	访客聊天已达到 IP、会话、指纹或线程用量上限。	注册或登录以继续。
`guest_signup_required`	`error_code`	`403`	访客聊天无法使用受限功能（例如上传）。	注册或登录以继续。
`guest_session_required`	`error_code`	`403`	访客会话 cookie 缺失或已过期。	刷新页面；SPA 会自动重新签发。
`guest_unavailable`	`error_code`	`503`	访客聊天暂时不可用（总开关 / 高流量）。	注册或登录以继续。
`provider_tool_rate_limit_exceeded`	`error_code`	`429`	账户已达到每日提供商工具调用上限。	等待重置后重试或升级套餐。
`log_range_limit_exceeded`	`error_code`	`402`	请求的日志区间超出允许窗口。	缩小日期范围。
`experiment_run_result_limit_exceeded`	`error_code`	`422`	实验运行会创建超过当前套餐允许的结果单元数。	减少数据集行或活跃候选项,或升级套餐。
`experiment_candidate_type_unsupported`	`error_code`	`422`	该实验候选项类型不支持仅提示词实验。	使用控制台提示词或已部署提示词候选项。
`experiment_run_unsupported_candidates`	`error_code`	`422`	实验运行包含无法在仅提示词实验中运行的活跃候选项。	归档不支持的候选项后重试。
`experiment_dataset_row_limit_exceeded`	`error_code`	`422`	数据集版本会超过 10,000 行限制。	减少 CSV 行数后重试。
`experiment_run_start_failed`	`error_code`	`503`	Fetch Hive 创建运行记录后未能启动实验工作流。	重试运行；如持续存在请联系支持。
`iteration_limit_exceeded`	`error_code`	`422`	一次工作流迭代超出了允许的循环次数。	减小输入规模或迭代次数。
`internal_server_error`	`error_code`	`500`	Fetch Hive 遇到了意外的内部错误。	稍后重试；如持续存在请联系支持。
`too_many_requests`	`error_code`	`429`	提供商或 Fetch Hive 因速率限制拒绝了请求。	退避后重试。
`concurrency_limit_reached`	`error_code`	`429`	账户已达到活跃工作流并发上限。	稍后重试或使用回调投递。
`validation_error`	`error_code`	`400`/`422`	请求参数在运行开始前无效。	修复请求体或查询参数。
`unsupported_provider`	`error_code`	`400`	该运行时路径不支持所配置的提供商。	选择受支持的提供商/模型。
`database_error`	`error_code`	`500`	Fetch Hive 无法完成所请求的操作。	稍后重试；如持续存在请联系支持。
`config_error`	`error_code`	`500`	运行时配置缺失或无效。	联系支持。
`provider_error`	`error_code`	`502`	模型提供商拒绝或失败了请求。	检查提供商状态/输入并重试。
`agent_completion_persistence_failed`	`error_code`	`503`	Fetch Hive 在提供商执行后无法保存智能体完成结果。	重试请求；如持续存在请联系支持。
`upstream_request_failed`	`error_code`	`502`/`504`	Fetch Hive 无法从上游服务获取成功响应。	稍后重试；如持续存在请联系支持。
`workflow_enqueue_failed`	`error_code`	`500`	一次工作流运行无法入队。	重新运行该工作流。
`not_found`	`error_code`	`404`	在已认证账户中找不到请求的资源。	检查标识符和账户上下文。
`resource_not_found`	`error_code`	`404`	未找到所请求的资源。	检查标识符和账户上下文。
`invalid_access`	`error_code`	`401`	控制台或公开请求未对所请求的账户进行身份验证。	重新登录后重试。
`unauthorized`	`error_code`	`401`	请求缺少有效授权。	重新登录后重试。
`forbidden`	`error_code`	`403`	调用方已认证但无权执行该操作。	使用有访问权限的账户或联系管理员。
`invalid_api_key`	`error_code`	`401`	全局或 API 密钥认证的请求使用了无效密钥。	检查 API 密钥后重试。
`invalid_request`	`error_code`	`400`	请求字段无效。	修复请求后重试。
`missing_required_field`	`error_code`	`422`	缺少必填的请求字段。	提供必填字段后重试。
`missing_required_header`	`error_code`	`400`	缺少必填的请求头。	发送必填的请求头后重试。
`validation_failed`	`error_code`	`422`	请求校验失败；详情会在 `errors` 或 `details` 中返回。	修复高亮字段后重试。
`payment_failed`	`error_code`	`422`	Stripe 支付流程失败。	检查支付方式后重试。
`credit_pack_pricing_changed`	`error_code`	`409`	托管 LLM 额度包报价缺失或已过期。	查看返回的购买摘要并确认更新后的总额。
`invalid_hosted_llm_credit_amount`	`error_code`	`422`	自定义托管 LLM 钱包充值金额缺失、格式无效、低于 10 美元、高于 999,999 美元，或不是整数美元。	请输入 10 至 999,999 美元之间的整数金额后重试。
`billing_configuration_missing`	`error_code`	`422`	请求的套餐或计费路径缺少服务端 Stripe 配置。	联系支持。
`stripe_customer_creation_failed`	`error_code`	`422`	Fetch Hive 无法为该账户创建或加载 Stripe 客户。	稍后重试；如持续存在请联系支持。
`promotion_code_invalid`	`error_code`	`200`	折扣码缺失、无效、已过期或被 Stripe 拒绝。	检查折扣码后重试。
`archive_restore_conflict`	`error_code`	`409`	该账户已有归档恢复在进行中。	等现有恢复完成后再重试。
`completion_resolution_failed`	`error_code`	`500`	Fetch Hive 无法将一次 completion 解析回其控制台 URL。	稍后重试；如持续存在请联系支持。
`integration_connection_failed`	`error_code`	`502`	集成连接无法发起或同步。	重新连接集成并重试。
`webhook_signature_invalid`	`error_code`	`400`	webhook 签名无法验证。	核对 webhook 签名密钥后重试。
`webhook_signature_not_configured`	`error_code`	`500`	服务端缺少 webhook 签名密钥。	配置 webhook 签名密钥后再重试。
`webhook_payload_invalid`	`error_code`	`400`	无法解析 webhook 载荷。	发送有效的 webhook 载荷。
`mcp_connection_failed`	`error_code`	`422`	工作区 MCP 服务器测试失败。	检查 MCP 服务器 URL、认证和响应格式。
`unsupported_resource_type`	`error_code`	`400`	请求的资源类型不受支持。	使用受支持的资源类型。

对于 workflow_step_limit_reached、workspace_limit_reached、api_rate_limit_exceeded 和 log_range_limit_exceeded，响应中也可能包含具有相同值的 code，以兼容较旧的客户端。