错误

错误格式以及每个错误码的 HTTP 状态、含义和处理方法——以及哪些错误可以安全重试。

格式

每个错误——无论来自 API 还是应用的端点——都具有相同的结构,并且从不包含堆栈跟踪:

{
  "error": {
    "code": "INVALID_STATE",
    "message": "Field company_size must be a number.",
    "request_id": "req_7Gm2xPq9Lk4sVt1RbN8w"
  }
}
字段说明
code下表中稳定的、机器可读的代码。请根据它进行分支判断——而不是根据 message。
message人类可读的解释。它可能会变化;不要解析它。
request_id请求的 ID,也会在 X-Request-ID 请求头中发送。联系支持团队时请附上它。
details可选的附加数据,取决于错误码(参见 details)。

错误码

请求与访问

代码状态含义怎么做
INVALID_REQUEST400请求格式错误:无效的 JSON、请求体不是 JSON 对象、无效的 Idempotency-Key 或查询参数——例如在 GET /v1/executions 上使用 limit=1000。修正请求。如果有出错的字段,details 会列出它们。
PAYLOAD_TOO_LARGE413请求体超过 128 KB(POST /mcp 为 1 MB,因为其工具可以携带决策 schema;POST /v1/decisions/{slug} 和 POST /v1/hooks/{token} 为 32 MB,因为其 state 可以携带文件)。发送更小的请求体——对于较大的 state,只发送问题需要的字段。参见限制。
INVALID_API_KEY401API 密钥缺失、格式错误、未知或已撤销。使用有效的密钥发送 Authorization: Bearer <key>。
UNAUTHORIZED401应用:你未登录、会话已过期或已被结束——通过在所有设备退出或更改密码;登录时电子邮件或密码错误也会返回此错误。带密钥的 Webhook URL:调用没有有效的 Dcision-Signature 或 Authorization: Bearer whsec_…。重新登录——或用当前的密钥为 webhook 调用签名。
FORBIDDEN403你不能执行此操作:在 /v1 之外使用 API 密钥;访问你不是其成员的工作区——此时 details.reason 为 "workspace_access";或执行你的角色不允许的操作——查看者不能更改任何内容;设置、服务商密钥、密钥(secrets)和成员需要管理员;计费、所有权和删除工作区需要所有者。只在 /v1 上使用 API 密钥。如需某个角色,请联系管理员或所有者——消息中会指明所需的角色。
NOT_FOUND404应用:执行记录、API 密钥、模板、套餐、结账会话、成员、邀请、投递或密钥在此工作区中不存在。Webhook URL:token 未知、已被轮换,或 webhook 已关闭。检查 ID——或从决策的高级标签页重新复制 webhook URL。
CONFLICT409更改与当前状态冲突:slug 已被占用或在首次部署后已锁定、草稿同时已被他人保存、并发的部署或创建、达到上限(50 个有效 API 密钥、50 个密钥、50 个待处理邀请、拥有 10 个工作区)、邀请已在工作区中的人、所有者未转让所有权就离开、删除有生效付费订阅的工作区、订阅已存在或不存在。重新加载,然后按照消息操作。

决策

代码状态含义怎么做
WORKSPACE_NOT_FOUND404合作伙伴模式:Dcision-Workspace 请求头或 {ref} 指向的不是 API 密钥所属工作区的子工作区。发送子工作区的 id 或 ext:<external_id>——参见子工作区。
SLUG_TAKEN409合作伙伴模式:把决策移动到一个已有相同 slug 决策的子工作区。details 包含 decision_id、executions、deliveries 和 replaceable(该副本从未运行过)。当 replaceable: true 时,发送 replace_empty: true 来替换该副本。否则请先重命名或删除子工作区中的决策。
DECISION_NOT_FOUND404API 密钥所属工作区中没有使用此 slug 的决策,或 slug 格式错误。检查 slug,并确认密钥属于该决策所在的工作区。
DECISION_NOT_DEPLOYED409决策存在,但从未部署过。在其部署标签页中部署它。
DECISION_DISABLED409决策的端点已停用。在其部署标签页中点击启用端点。
INVALID_STATE422state 与决策的 state schema 不匹配,或者过大——无论是单独过大,还是与问题一起超出了引擎的 token 预算。message 会指明字段或限制。修正 state;对于 token 预算,只发送问题需要的字段。不要原样重试。
INVALID_SCHEMA422决策 schema 无效——在保存或部署草稿时。details 会列出每个问题。在编辑器中修复这些问题(跳转到错误)。
IDEMPOTENCY_CONFLICT409该 Idempotency-Key 在过去 24 小时内已用于另一个不同的请求——或者,带有 Retry-After: 1 时,使用此键的第一个请求仍在运行。带有 Retry-After 时:等待后使用相同的键重试,以获取存储的响应。没有时:为新请求使用新键——参见幂等性。

限制与计费

代码状态含义怎么做
RATE_LIMITED429你的工作区在当前分钟内的请求过多——或达到了 Playground 自身的限制,或者在应用中,计费操作(结账、更改套餐、门户……)、邀请、登录验证码或登录尝试过多。等待 Retry-After 秒后再重试——参见速率限制。
CREDITS_EXHAUSTED402本周期套餐包含的决策已用完,且工作区没有剩余的额度。所有者在计费页面(details.billingUrl)添加额度或开启自动充值,或者升级套餐。在此之前重试没有帮助。
SPEND_CAP_REACHED402已达到工作区在本计费周期的支出上限。所有者在计费页面提高或移除上限,或者等到 details.periodEnd。
QUOTA_EXCEEDED402配置了硬性上限——或没有每 100 万次决策价格——的套餐已用完本周期包含的所有决策,因此无法继续用额度运行。升级套餐,或等到 details.periodEnd。提前重试没有帮助。
PLAN_LIMIT_REACHED402工作区的决策数量已达到其套餐的上限。删除一个决策或升级套餐。
PAYMENT_FAILED402更改套餐时银行卡被拒。更新支付方式后重试。
BILLING_NOT_CONFIGURED503该套餐、计费间隔或币种暂时无法在线购买。稍后再试,或发送邮件至 sales@dcision.io。
BILLING_PROVIDER_ERROR502支付服务商未能处理该请求。稍后再试。

引擎

在返回以下错误之前,Dcision 已经对暂时性的引擎故障进行了重试——在决策的 timeoutMs 内最多重试 2 次。设置了 onEngineError: "fallback" 的决策则会改为返回带 fallback 行动的 200,适用于下面除 ENGINE_NOT_CONFIGURED 之外的所有代码——参见决策设置。

代码状态含义怎么做
ENGINE_NOT_CONFIGURED424工作区没有可用的引擎凭据:选择了我自己的服务商密钥,但没有为该服务商保存密钥,或者 Dcision 的引擎密钥不可用。在 设置 → 引擎 中添加密钥,或切换到 Dcision 的密钥。
ENGINE_TIMEOUT504引擎未在决策的 timeoutMs 内作答。使用退避和相同的 Idempotency-Key 重试;如果经常发生,请调高 timeoutMs。
ENGINE_RATE_LIMITED503引擎提供商过载或触发了速率限制,或者 Dcision 共享的引擎密钥在截止时间之前没有空闲槽位。使用退避重试。使用你自己的密钥时,请检查提供商的限制。
ENGINE_UNAVAILABLE503引擎提供商出错或无法访问。使用退避重试。
ENGINE_INVALID_REQUEST502提供商拒绝了请求;消息中包含其原因。通常不是暂时性的:检查 state 和模型,然后附上请求 ID 联系支持团队。
ENGINE_AUTH_FAILED502提供商拒绝了引擎密钥。在 设置 → 引擎 中修正或更换你的服务商密钥。
ENGINE_ERROR502引擎的回答不符合决策的契约(缺少回答或回答未知)。重试一次;如果仍然存在,请附上请求 ID 联系支持团队。

服务器

代码状态含义怎么做
INTERNAL_ERROR500Dcision 一侧的意外错误。使用退避重试;如果仍然存在,请附上请求 ID 联系支持团队。

重试

可以重试不要原样重试
429 RATE_LIMITED——在 Retry-After 之后400、401、403、404、413、422
带有 Retry-After 的 409 IDEMPOTENCY_CONFLICT——使用相同的键,等待之后其他任何 409
500 INTERNAL_ERROR402 CREDITS_EXHAUSTED、SPEND_CAP_REACHED、QUOTA_EXCEEDED、PLAN_LIMIT_REACHED、PAYMENT_FAILED
503 ENGINE_RATE_LIMITED、ENGINE_UNAVAILABLE424 ENGINE_NOT_CONFIGURED
504 ENGINE_TIMEOUT502 ENGINE_AUTH_FAILED、ENGINE_INVALID_REQUEST
502 ENGINE_ERROR——一次
你这一侧的网络错误和超时

请发送 Idempotency-Key,这样在响应丢失后重试时,决策不会运行两次——也不会计费两次。完整的客户端参见幂等重试。

错误从不计费,引擎错误时的 fallback 也不计费。无效的 state 和引擎故障会被记录为状态为错误的执行记录,方便你检查——在应用中,或通过 GET /v1/executions?status=error。

详情

details 为部分错误码携带结构化数据:

422 INVALID_SCHEMA
{
  "error": {
    "code": "INVALID_SCHEMA",
    "message": "The decision schema is invalid.",
    "request_id": "req_7Gm2xPq9Lk4sVt1RbN8w",
    "details": [{ "path": "questions.0.options", "message": "Add at least 2 options (besides \"other\")." }]
  }
}
402 CREDITS_EXHAUSTED
{
  "error": {
    "code": "CREDITS_EXHAUSTED",
    "message": "The 2.5M decisions included in the Developer plan are used up and the workspace has no credits left. Add credits or turn on automatic recharge.",
    "request_id": "req_Lz4Wq8nT1vXc7Rm2Kp9H",
    "details": {
      "used": 2500000,
      "included": 2500000,
      "availableCents": 0,
      "currency": "usd",
      "billingUrl": "https://app.dcision.io/billing"
    }
  }
}
402 SPEND_CAP_REACHED
{
  "error": {
    "code": "SPEND_CAP_REACHED",
    "message": "The workspace reached its spend cap of $50.00 for this billing cycle. Raise the cap or wait until 2026-11-01.",
    "request_id": "req_Qm8Vr2Lx5Nc1Tw7Hk4Jd",
    "details": {
      "spendCapCents": 5000,
      "spentCents": 5000,
      "currency": "usd",
      "periodEnd": "2026-11-01T00:00:00.000Z",
      "billingUrl": "https://app.dcision.io/billing"
    }
  }
}
403 FORBIDDEN — not a member of the workspace
{
  "error": {
    "code": "FORBIDDEN",
    "message": "You don't have access to this workspace.",
    "request_id": "req_Pw3Nx8Kd1Lq6Tz2Vb9Rc",
    "details": { "reason": "workspace_access" }
  }
}
代码details
INVALID_REQUEST有可用信息时,为无效字段提供 [{ "path", "message" }]
INVALID_SCHEMA[{ "path", "message" }]——每个 schema 问题
CREDITS_EXHAUSTEDused、included、availableCents(剩余额度,以 currency 的分为单位——为零或略为负数)、currency(usd 或 brl)、billingUrl
SPEND_CAP_REACHEDspendCapCents、spentCents(本周期使用额度的支出,以分为单位)、currency、periodEnd(ISO 8601)、billingUrl
QUOTA_EXCEEDEDused、included、periodEnd(ISO 8601)、upgradeUrl
PLAN_LIMIT_REACHEDlimit、used、upgradeUrl
FORBIDDEN(工作区访问){ "reason": "workspace_access" }——你(已经)不是该工作区的成员。因角色而被拒绝时不带 details。
CONFLICT(过期的草稿)currentRevision
PAYMENT_FAILED来自卡组织的 code、declineCode

本页内容