错误代码

Fetch Hive API 错误包含人类可读的 message、一个稳定的 error_code，以及作为同一消息兼容别名的 error 字段。较旧的套餐和速率限制响应可能还会包含 code；请将 code 视为已弃用的别名，并优先读取 error_code。 Rails 拥有错误代码目录以及本地化消息和客户端操作模板。账户范围的 API 响应在返回文案时使用已认证账户的语言设置。Rust 生成的校验/预检错误使用相同的 JSON 信封，并根据已认证账户的语言对人类可读的 error/message 字段进行本地化，未命中时回退到英文。新的面向 API 的错误代码必须添加到 Rails 目录；Rust 和 React 常量会根据该源进行检查。

目录接口

使用 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 密钥已达到每日请求上限。	等待重置后重试或升级套餐。
`log_range_limit_exceeded`	`error_code`	`402`	请求的日志区间超出允许窗口。	缩小日期范围。
`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`	Rust 公开 API 在分发前拒绝了请求参数。	修复请求体或查询参数。
`unsupported_provider`	`error_code`	`400`	该运行时路径不支持所配置的提供商。	选择受支持的提供商/模型。
`database_error`	`error_code`	`500`	Rust 公开 API 无法完成一次数据库操作。	稍后重试；如持续存在请联系支持。
`config_error`	`error_code`	`500`	运行时配置缺失或无效。	联系支持。
`provider_error`	`error_code`	`502`	模型提供商拒绝或失败了请求。	检查提供商状态/输入并重试。
`upstream_request_failed`	`error_code`	`502`/`504`	Rust 无法从 Rails 或其他上游运行时获取成功响应。	稍后重试；如持续存在请联系支持。
`workflow_enqueue_failed`	`error_code`	`500`	一次工作流运行无法入队。	重新运行该工作流。
`not_found`	`error_code`	`404`	在已认证账户中找不到请求的资源。	检查标识符和账户上下文。
`resource_not_found`	`error_code`	`404`	未找到指定的 Rails 资源。	检查标识符和账户上下文。
`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`	Rails 校验失败；详情会在 `errors` 或 `details` 中返回。	修复高亮字段后重试。
`payment_failed`	`error_code`	`422`	Stripe 支付流程失败。	检查支付方式后重试。
`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，以兼容较旧的客户端。

​错误代码

​目录接口

​JSON 错误结构

​SSE 错误结构

​代码列表

错误代码

目录接口

JSON 错误结构

SSE 错误结构

代码列表