错误
错误格式以及每个错误码的 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_REQUEST | 400 | 请求格式错误:无效的 JSON、请求体不是 JSON 对象、无效的 Idempotency-Key 或查询参数——例如在 GET /v1/executions 上使用 limit=1000。 | 修正请求。如果有出错的字段,details 会列出它们。 |
PAYLOAD_TOO_LARGE | 413 | 请求体超过 128 KB(POST /mcp 为 1 MB,因为其工具可以携带决策 schema;POST /v1/decisions/{slug} 和 POST /v1/hooks/{token} 为 32 MB,因为其 state 可以携带文件)。 | 发送更小的请求体——对于较大的 state,只发送问题需要的字段。参见限制。 |
INVALID_API_KEY | 401 | API 密钥缺失、格式错误、未知或已撤销。 | 使用有效的密钥发送 Authorization: Bearer <key>。 |
UNAUTHORIZED | 401 | 应用:你未登录、会话已过期或已被结束——通过在所有设备退出或更改密码;登录时电子邮件或密码错误也会返回此错误。带密钥的 Webhook URL:调用没有有效的 Dcision-Signature 或 Authorization: Bearer whsec_…。 | 重新登录——或用当前的密钥为 webhook 调用签名。 |
FORBIDDEN | 403 | 你不能执行此操作:在 /v1 之外使用 API 密钥;访问你不是其成员的工作区——此时 details.reason 为 "workspace_access";或执行你的角色不允许的操作——查看者不能更改任何内容;设置、服务商密钥、密钥(secrets)和成员需要管理员;计费、所有权和删除工作区需要所有者。 | 只在 /v1 上使用 API 密钥。如需某个角色,请联系管理员或所有者——消息中会指明所需的角色。 |
NOT_FOUND | 404 | 应用:执行记录、API 密钥、模板、套餐、结账会话、成员、邀请、投递或密钥在此工作区中不存在。Webhook URL:token 未知、已被轮换,或 webhook 已关闭。 | 检查 ID——或从决策的高级标签页重新复制 webhook URL。 |
CONFLICT | 409 | 更改与当前状态冲突:slug 已被占用或在首次部署后已锁定、草稿同时已被他人保存、并发的部署或创建、达到上限(50 个有效 API 密钥、50 个密钥、50 个待处理邀请、拥有 10 个工作区)、邀请已在工作区中的人、所有者未转让所有权就离开、删除有生效付费订阅的工作区、订阅已存在或不存在。 | 重新加载,然后按照消息操作。 |
决策
| 代码 | 状态 | 含义 | 怎么做 |
|---|---|---|---|
WORKSPACE_NOT_FOUND | 404 | 合作伙伴模式:Dcision-Workspace 请求头或 {ref} 指向的不是 API 密钥所属工作区的子工作区。 | 发送子工作区的 id 或 ext:<external_id>——参见子工作区。 |
SLUG_TAKEN | 409 | 合作伙伴模式:把决策移动到一个已有相同 slug 决策的子工作区。details 包含 decision_id、executions、deliveries 和 replaceable(该副本从未运行过)。 | 当 replaceable: true 时,发送 replace_empty: true 来替换该副本。否则请先重命名或删除子工作区中的决策。 |
DECISION_NOT_FOUND | 404 | API 密钥所属工作区中没有使用此 slug 的决策,或 slug 格式错误。 | 检查 slug,并确认密钥属于该决策所在的工作区。 |
DECISION_NOT_DEPLOYED | 409 | 决策存在,但从未部署过。 | 在其部署标签页中部署它。 |
DECISION_DISABLED | 409 | 决策的端点已停用。 | 在其部署标签页中点击启用端点。 |
INVALID_STATE | 422 | state 与决策的 state schema 不匹配,或者过大——无论是单独过大,还是与问题一起超出了引擎的 token 预算。message 会指明字段或限制。 | 修正 state;对于 token 预算,只发送问题需要的字段。不要原样重试。 |
INVALID_SCHEMA | 422 | 决策 schema 无效——在保存或部署草稿时。details 会列出每个问题。 | 在编辑器中修复这些问题(跳转到错误)。 |
IDEMPOTENCY_CONFLICT | 409 | 该 Idempotency-Key 在过去 24 小时内已用于另一个不同的请求——或者,带有 Retry-After: 1 时,使用此键的第一个请求仍在运行。 | 带有 Retry-After 时:等待后使用相同的键重试,以获取存储的响应。没有时:为新请求使用新键——参见幂等性。 |
限制与计费
| 代码 | 状态 | 含义 | 怎么做 |
|---|---|---|---|
RATE_LIMITED | 429 | 你的工作区在当前分钟内的请求过多——或达到了 Playground 自身的限制,或者在应用中,计费操作(结账、更改套餐、门户……)、邀请、登录验证码或登录尝试过多。 | 等待 Retry-After 秒后再重试——参见速率限制。 |
CREDITS_EXHAUSTED | 402 | 本周期套餐包含的决策已用完,且工作区没有剩余的额度。 | 所有者在计费页面(details.billingUrl)添加额度或开启自动充值,或者升级套餐。在此之前重试没有帮助。 |
SPEND_CAP_REACHED | 402 | 已达到工作区在本计费周期的支出上限。 | 所有者在计费页面提高或移除上限,或者等到 details.periodEnd。 |
QUOTA_EXCEEDED | 402 | 配置了硬性上限——或没有每 100 万次决策价格——的套餐已用完本周期包含的所有决策,因此无法继续用额度运行。 | 升级套餐,或等到 details.periodEnd。提前重试没有帮助。 |
PLAN_LIMIT_REACHED | 402 | 工作区的决策数量已达到其套餐的上限。 | 删除一个决策或升级套餐。 |
PAYMENT_FAILED | 402 | 更改套餐时银行卡被拒。 | 更新支付方式后重试。 |
BILLING_NOT_CONFIGURED | 503 | 该套餐、计费间隔或币种暂时无法在线购买。 | 稍后再试,或发送邮件至 sales@dcision.io。 |
BILLING_PROVIDER_ERROR | 502 | 支付服务商未能处理该请求。 | 稍后再试。 |
引擎
在返回以下错误之前,Dcision 已经对暂时性的引擎故障进行了重试——在决策的 timeoutMs 内最多重试 2 次。设置了 onEngineError: "fallback" 的决策则会改为返回带 fallback 行动的 200,适用于下面除 ENGINE_NOT_CONFIGURED 之外的所有代码——参见决策设置。
| 代码 | 状态 | 含义 | 怎么做 |
|---|---|---|---|
ENGINE_NOT_CONFIGURED | 424 | 工作区没有可用的引擎凭据:选择了我自己的服务商密钥,但没有为该服务商保存密钥,或者 Dcision 的引擎密钥不可用。 | 在 设置 → 引擎 中添加密钥,或切换到 Dcision 的密钥。 |
ENGINE_TIMEOUT | 504 | 引擎未在决策的 timeoutMs 内作答。 | 使用退避和相同的 Idempotency-Key 重试;如果经常发生,请调高 timeoutMs。 |
ENGINE_RATE_LIMITED | 503 | 引擎提供商过载或触发了速率限制,或者 Dcision 共享的引擎密钥在截止时间之前没有空闲槽位。 | 使用退避重试。使用你自己的密钥时,请检查提供商的限制。 |
ENGINE_UNAVAILABLE | 503 | 引擎提供商出错或无法访问。 | 使用退避重试。 |
ENGINE_INVALID_REQUEST | 502 | 提供商拒绝了请求;消息中包含其原因。 | 通常不是暂时性的:检查 state 和模型,然后附上请求 ID 联系支持团队。 |
ENGINE_AUTH_FAILED | 502 | 提供商拒绝了引擎密钥。 | 在 设置 → 引擎 中修正或更换你的服务商密钥。 |
ENGINE_ERROR | 502 | 引擎的回答不符合决策的契约(缺少回答或回答未知)。 | 重试一次;如果仍然存在,请附上请求 ID 联系支持团队。 |
服务器
| 代码 | 状态 | 含义 | 怎么做 |
|---|---|---|---|
INTERNAL_ERROR | 500 | Dcision 一侧的意外错误。 | 使用退避重试;如果仍然存在,请附上请求 ID 联系支持团队。 |
重试
| 可以重试 | 不要原样重试 |
|---|---|
429 RATE_LIMITED——在 Retry-After 之后 | 400、401、403、404、413、422 |
带有 Retry-After 的 409 IDEMPOTENCY_CONFLICT——使用相同的键,等待之后 | 其他任何 409 |
500 INTERNAL_ERROR | 402 CREDITS_EXHAUSTED、SPEND_CAP_REACHED、QUOTA_EXCEEDED、PLAN_LIMIT_REACHED、PAYMENT_FAILED |
503 ENGINE_RATE_LIMITED、ENGINE_UNAVAILABLE | 424 ENGINE_NOT_CONFIGURED |
504 ENGINE_TIMEOUT | 502 ENGINE_AUTH_FAILED、ENGINE_INVALID_REQUEST |
502 ENGINE_ERROR——一次 | |
| 你这一侧的网络错误和超时 |
请发送 Idempotency-Key,这样在响应丢失后重试时,决策不会运行两次——也不会计费两次。完整的客户端参见幂等重试。
错误从不计费,引擎错误时的 fallback 也不计费。无效的 state 和引擎故障会被记录为状态为错误的执行记录,方便你检查——在应用中,或通过 GET /v1/executions?status=error。
详情
details 为部分错误码携带结构化数据:
{
"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\")." }]
}
}{
"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"
}
}
}{
"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"
}
}
}{
"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_EXHAUSTED | used、included、availableCents(剩余额度,以 currency 的分为单位——为零或略为负数)、currency(usd 或 brl)、billingUrl |
SPEND_CAP_REACHED | spendCapCents、spentCents(本周期使用额度的支出,以分为单位)、currency、periodEnd(ISO 8601)、billingUrl |
QUOTA_EXCEEDED | used、included、periodEnd(ISO 8601)、upgradeUrl |
PLAN_LIMIT_REACHED | limit、used、upgradeUrl |
FORBIDDEN(工作区访问) | { "reason": "workspace_access" }——你(已经)不是该工作区的成员。因角色而被拒绝时不带 details。 |
CONFLICT(过期的草稿) | currentRevision |
PAYMENT_FAILED | 来自卡组织的 code、declineCode |