跳到正文
Indiana
控制台
开发文档
章节目录 / 请求与错误

请求与错误

身份校验、超时、幂等与排错。

SDK 示例对应当前 API。核对匹配版本与 HTTP 接入方式

API v1更新于

请求与错误

凭据决定 App、环境、身份与权限；范围头只核对。客户请求不接受任意 customerId。Funnel 命令保留原 requestId、当前节点与 revision；超时 retry 重放原输入。

协议 0.5 的错误响应为 { requestId, error: { code, message, retryable, recovery, retryAfterSeconds? } }。按 code 与 recovery 处理，message 用于展示。

当前 HTTP 接口与权限
方法路径调用方权限
POST/api/v1/invoices/templatesserverbilling:read
POST/api/v1/invoices/previewserverbilling:write
POST/api/v1/invoices/createserverbilling:write
POST/api/v1/invoices/manageserverbilling:write
POST/api/v1/invoices/operations/readserverbilling:read
POST/api/v1/invoices/listserverbilling:read
POST/api/v1/invoices/readserverbilling:read
POST/api/v1/code-references/configservercode-references:read
POST/api/v1/code-referencesservercode-references:write
GET/api/v1/featuresmixedfeatures:read
POST/api/v1/features/evaluatemixedfeatures:read
POST/api/v1/eventsmixedevents:write
POST/api/v1/billing/setup-paymentmixedbilling:write
POST/api/v1/billing/payment-setupmixedbilling:read
POST/api/v1/subscriptions/batches/previewserverbilling:write
POST/api/v1/subscriptions/batches/confirmserverbilling:write
POST/api/v1/subscriptions/batches/readserverbilling:read
POST/api/v1/subscriptions/batches/abandonserverbilling:write
POST/api/v1/subscriptions/trials/manageserverbilling:write
POST/api/v1/subscriptions/trials/readserverbilling:read
POST/api/v1/subscriptions/listserverbilling:read
POST/api/v1/purchases/listserverbilling:read
POST/api/v1/subscriptions/conflicts/listserverbilling:read
POST/api/v1/subscriptions/conflicts/retryserverbilling:write
POST/api/v1/ai/pricing/readservercredits:read
POST/api/v1/usage/readservercredits:read
POST/api/v1/usage/setservercredits:manage
POST/api/v1/subscriptions/refunds/previewserverbilling:read
POST/api/v1/subscriptions/refunds/confirmserverbilling:write
POST/api/v1/subscriptions/refunds/readserverbilling:read
POST/api/v1/subscriptions/preview-updatemixedbilling:read
POST/api/v1/subscriptions/updatemixedbilling:write
POST/api/v1/subscriptions/updates/readmixedbilling:read
POST/api/v1/subscriptions/native/restoremixedbilling:write
POST/api/v1/subscriptions/verifyserverbilling:read
POST/api/v1/subscriptions/preview-attachmixedbilling:read
POST/api/v1/subscriptions/attachmixedbilling:write
POST/api/v1/subscriptions/operations/readmixedbilling:read
POST/api/v1/balances/grants/manageservercredits:manage
POST/api/v1/balances/source/readservercredits:read
POST/api/v1/balances/source/adjustservercredits:manage
POST/api/v1/balances/grants/listservercredits:read
POST/api/v1/billing/controls/readcustomerbilling:read
POST/api/v1/billing/authorizations/preparecustomerbilling:write
POST/api/v1/billing/authorizations/confirmcustomerbilling:write
POST/api/v1/billing/couponscustomerbilling:write
POST/api/v1/billing/authorizations/revokecustomerbilling:write
POST/api/v1/billing/invoices/readcustomerbilling:read
POST/api/v1/billing/invoices/confirm-adjustmentcustomerbilling:write
POST/api/v1/billing/controls/manageserverbilling:write
POST/api/v1/customersservercustomers:write
POST/api/v1/customers/getservercustomers:read
POST/api/v1/customers/listservercustomers:read
POST/api/v1/customers/updateservercustomers:write
POST/api/v1/customer-sessionsserversessions:create
POST/api/v1/customer-sessions/renewserversessions:create
POST/api/v1/customer-sessions/revokeserversessions:create
POST/api/v1/customers/guestsserversessions:create
POST/api/v1/customers/guests/sessionserversessions:create
POST/api/v1/customers/guests/claimservercustomers:write
POST/api/v1/entitlements/checkmixedentitlements:read
POST/api/v1/offerings/resolvemixedentitlements:read
POST/api/v1/paywalls/resolvemixedentitlements:read
POST/api/v1/customer-holdingsmixedentitlements:read
POST/api/v1/customer-ledgermixedcredits:read
POST/api/v1/billing/invoices/detailmixedbilling:read
POST/api/v1/credit-statements/readmixedcredits:read
POST/api/v1/balances/quotemixedcredits:read
POST/api/v1/usage/trackservercredits:consume
POST/api/v1/balances/executeservercredits:consume
POST/api/v1/usage/entitiesservercredits:manage
POST/api/v1/usage/analyticsservercredits:read
POST/api/v1/credits/analyticsservercredits:read
POST/api/v1/usage/batchservercredits:consume
POST/api/v1/usage/batch/readservercredits:read
GET/api/v1/offerscustomeroffers:resolve
POST/api/v1/offers/grantmixedoffers:grant
POST/api/v1/offers/redemptionsserverbilling:write
POST/api/v1/offers/redeemcustomeroffers:resolve
POST/api/v1/rewards/redeemcustomeroffers:resolve
POST/api/v1/rewards/referral-codecustomeroffers:resolve
POST/api/v1/rewards/product/claimcustomeroffers:resolve
POST/api/v1/seats/listservercustomers:read
POST/api/v1/seats/manageserverbilling:write

当前 HTTP 接口与权限

  • POST

    路径
    /api/v1/invoices/templates
    调用方
    server
    权限
    billing:read

  • POST

    路径
    /api/v1/invoices/preview
    调用方
    server
    权限
    billing:write

  • POST

    路径
    /api/v1/invoices/create
    调用方
    server
    权限
    billing:write

  • POST

    路径
    /api/v1/invoices/manage
    调用方
    server
    权限
    billing:write

  • POST

    路径
    /api/v1/invoices/operations/read
    调用方
    server
    权限
    billing:read

  • POST

    路径
    /api/v1/invoices/list
    调用方
    server
    权限
    billing:read

  • POST

    路径
    /api/v1/invoices/read
    调用方
    server
    权限
    billing:read

  • POST

    路径
    /api/v1/code-references/config
    调用方
    server
    权限
    code-references:read

  • POST

    路径
    /api/v1/code-references
    调用方
    server
    权限
    code-references:write

  • GET

    路径
    /api/v1/features
    调用方
    mixed
    权限
    features:read

  • POST

    路径
    /api/v1/features/evaluate
    调用方
    mixed
    权限
    features:read

  • POST

    路径
    /api/v1/events
    调用方
    mixed
    权限
    events:write

  • POST

    路径
    /api/v1/billing/setup-payment
    调用方
    mixed
    权限
    billing:write

  • POST

    路径
    /api/v1/billing/payment-setup
    调用方
    mixed
    权限
    billing:read

  • POST

    路径
    /api/v1/subscriptions/batches/preview
    调用方
    server
    权限
    billing:write

  • POST

    路径
    /api/v1/subscriptions/batches/confirm
    调用方
    server
    权限
    billing:write

  • POST

    路径
    /api/v1/subscriptions/batches/read
    调用方
    server
    权限
    billing:read

  • POST

    路径
    /api/v1/subscriptions/batches/abandon
    调用方
    server
    权限
    billing:write

  • POST

    路径
    /api/v1/subscriptions/trials/manage
    调用方
    server
    权限
    billing:write

  • POST

    路径
    /api/v1/subscriptions/trials/read
    调用方
    server
    权限
    billing:read

  • POST

    路径
    /api/v1/subscriptions/list
    调用方
    server
    权限
    billing:read

  • POST

    路径
    /api/v1/purchases/list
    调用方
    server
    权限
    billing:read

  • POST

    路径
    /api/v1/subscriptions/conflicts/list
    调用方
    server
    权限
    billing:read

  • POST

    路径
    /api/v1/subscriptions/conflicts/retry
    调用方
    server
    权限
    billing:write

  • POST

    路径
    /api/v1/ai/pricing/read
    调用方
    server
    权限
    credits:read

  • POST

    路径
    /api/v1/usage/read
    调用方
    server
    权限
    credits:read

  • POST

    路径
    /api/v1/usage/set
    调用方
    server
    权限
    credits:manage

  • POST

    路径
    /api/v1/subscriptions/refunds/preview
    调用方
    server
    权限
    billing:read

  • POST

    路径
    /api/v1/subscriptions/refunds/confirm
    调用方
    server
    权限
    billing:write

  • POST

    路径
    /api/v1/subscriptions/refunds/read
    调用方
    server
    权限
    billing:read

  • POST

    路径
    /api/v1/subscriptions/preview-update
    调用方
    mixed
    权限
    billing:read

  • POST

    路径
    /api/v1/subscriptions/update
    调用方
    mixed
    权限
    billing:write

  • POST

    路径
    /api/v1/subscriptions/updates/read
    调用方
    mixed
    权限
    billing:read

  • POST

    路径
    /api/v1/subscriptions/native/restore
    调用方
    mixed
    权限
    billing:write

  • POST

    路径
    /api/v1/subscriptions/verify
    调用方
    server
    权限
    billing:read

  • POST

    路径
    /api/v1/subscriptions/preview-attach
    调用方
    mixed
    权限
    billing:read

  • POST

    路径
    /api/v1/subscriptions/attach
    调用方
    mixed
    权限
    billing:write

  • POST

    路径
    /api/v1/subscriptions/operations/read
    调用方
    mixed
    权限
    billing:read

  • POST

    路径
    /api/v1/balances/grants/manage
    调用方
    server
    权限
    credits:manage

  • POST

    路径
    /api/v1/balances/source/read
    调用方
    server
    权限
    credits:read

  • POST

    路径
    /api/v1/balances/source/adjust
    调用方
    server
    权限
    credits:manage

  • POST

    路径
    /api/v1/balances/grants/list
    调用方
    server
    权限
    credits:read

  • POST

    路径
    /api/v1/billing/controls/read
    调用方
    customer
    权限
    billing:read

  • POST

    路径
    /api/v1/billing/authorizations/prepare
    调用方
    customer
    权限
    billing:write

  • POST

    路径
    /api/v1/billing/authorizations/confirm
    调用方
    customer
    权限
    billing:write

  • POST

    路径
    /api/v1/billing/coupons
    调用方
    customer
    权限
    billing:write

  • POST

    路径
    /api/v1/billing/authorizations/revoke
    调用方
    customer
    权限
    billing:write

  • POST

    路径
    /api/v1/billing/invoices/read
    调用方
    customer
    权限
    billing:read

  • POST

    路径
    /api/v1/billing/invoices/confirm-adjustment
    调用方
    customer
    权限
    billing:write

  • POST

    路径
    /api/v1/billing/controls/manage
    调用方
    server
    权限
    billing:write

  • POST

    路径
    /api/v1/customers
    调用方
    server
    权限
    customers:write

  • POST

    路径
    /api/v1/customers/get
    调用方
    server
    权限
    customers:read

  • POST

    路径
    /api/v1/customers/list
    调用方
    server
    权限
    customers:read

  • POST

    路径
    /api/v1/customers/update
    调用方
    server
    权限
    customers:write

  • POST

    路径
    /api/v1/customer-sessions
    调用方
    server
    权限
    sessions:create

  • POST

    路径
    /api/v1/customer-sessions/renew
    调用方
    server
    权限
    sessions:create

  • POST

    路径
    /api/v1/customer-sessions/revoke
    调用方
    server
    权限
    sessions:create

  • POST

    路径
    /api/v1/customers/guests
    调用方
    server
    权限
    sessions:create

  • POST

    路径
    /api/v1/customers/guests/session
    调用方
    server
    权限
    sessions:create

  • POST

    路径
    /api/v1/customers/guests/claim
    调用方
    server
    权限
    customers:write

  • POST

    路径
    /api/v1/entitlements/check
    调用方
    mixed
    权限
    entitlements:read

  • POST

    路径
    /api/v1/offerings/resolve
    调用方
    mixed
    权限
    entitlements:read

  • POST

    路径
    /api/v1/paywalls/resolve
    调用方
    mixed
    权限
    entitlements:read

  • POST

    路径
    /api/v1/customer-holdings
    调用方
    mixed
    权限
    entitlements:read

  • POST

    路径
    /api/v1/customer-ledger
    调用方
    mixed
    权限
    credits:read

  • POST

    路径
    /api/v1/billing/invoices/detail
    调用方
    mixed
    权限
    billing:read

  • POST

    路径
    /api/v1/credit-statements/read
    调用方
    mixed
    权限
    credits:read

  • POST

    路径
    /api/v1/balances/quote
    调用方
    mixed
    权限
    credits:read

  • POST

    路径
    /api/v1/usage/track
    调用方
    server
    权限
    credits:consume

  • POST

    路径
    /api/v1/balances/execute
    调用方
    server
    权限
    credits:consume

  • POST

    路径
    /api/v1/usage/entities
    调用方
    server
    权限
    credits:manage

  • POST

    路径
    /api/v1/usage/analytics
    调用方
    server
    权限
    credits:read

  • POST

    路径
    /api/v1/credits/analytics
    调用方
    server
    权限
    credits:read

  • POST

    路径
    /api/v1/usage/batch
    调用方
    server
    权限
    credits:consume

  • POST

    路径
    /api/v1/usage/batch/read
    调用方
    server
    权限
    credits:read

  • GET

    路径
    /api/v1/offers
    调用方
    customer
    权限
    offers:resolve

  • POST

    路径
    /api/v1/offers/grant
    调用方
    mixed
    权限
    offers:grant

  • POST

    路径
    /api/v1/offers/redemptions
    调用方
    server
    权限
    billing:write

  • POST

    路径
    /api/v1/offers/redeem
    调用方
    customer
    权限
    offers:resolve

  • POST

    路径
    /api/v1/rewards/redeem
    调用方
    customer
    权限
    offers:resolve

  • POST

    路径
    /api/v1/rewards/referral-code
    调用方
    customer
    权限
    offers:resolve

  • POST

    路径
    /api/v1/rewards/product/claim
    调用方
    customer
    权限
    offers:resolve

  • POST

    路径
    /api/v1/seats/list
    调用方
    server
    权限
    customers:read

  • POST

    路径
    /api/v1/seats/manage
    调用方
    server
    权限
    billing:write
当前 API Key 权限
权限
customers:read
customers:write
entitlements:read
sessions:create
funnels:run
offers:resolve
offers:grant
billing:read
billing:write
credits:read
credits:consume
credits:manage
features:read
events:write
code-references:read
code-references:write

当前 API Key 权限

  • customers:read

  • customers:write

  • entitlements:read

  • sessions:create

  • funnels:run

  • offers:resolve

  • offers:grant

  • billing:read

  • billing:write

  • credits:read

  • credits:consume

  • credits:manage

  • features:read

  • events:write

  • code-references:read

  • code-references:write

服务端错误码
HTTPcode含义
400INVALID_PROTOCOL_VERSIONSDK 协议标识格式无效，或与 SDK 版本不一致
400UNSUPPORTED_PROTOCOL_VERSION请求的 SDK 协议尚未实现或不受支持
400INVALID_REQUEST请求体或参数不符合接口定义
401UNAUTHENTICATED缺少、无效、过期或已撤销的凭据
403FORBIDDEN权限不足，或浏览器来源不在允许列表
403SCOPE_MISMATCH校验头与凭据所属 App / 环境不一致
404NOT_FOUND当前 App 与环境里没有这个对象
409CONFLICT与已有数据冲突（例如同一 eventId 内容不同）
410PROTOCOL_RETIRED请求的 SDK 协议已结束支持，请按迁移指南升级
413PAYLOAD_TOO_LARGE请求体超过 16 KiB
429RATE_LIMITED请求频率超出限制，请稍后重试
500INTERNAL_ERROR内部失败或响应不符合契约；不返回内部异常细节
501NOT_CONFIGURED当前 App 与环境缺少所需集成配置
501CAPABILITY_UNAVAILABLE当前运行版本或执行模式尚未开放该操作；重试不会启用能力
503SERVICE_UNAVAILABLE服务暂时不可用，请稍后重试

服务端错误码

  • INVALID_PROTOCOL_VERSION400

    含义
    SDK 协议标识格式无效，或与 SDK 版本不一致

  • UNSUPPORTED_PROTOCOL_VERSION400

    含义
    请求的 SDK 协议尚未实现或不受支持

  • INVALID_REQUEST400

    含义
    请求体或参数不符合接口定义

  • UNAUTHENTICATED401

    含义
    缺少、无效、过期或已撤销的凭据

  • FORBIDDEN403

    含义
    权限不足，或浏览器来源不在允许列表

  • SCOPE_MISMATCH403

    含义
    校验头与凭据所属 App / 环境不一致

  • NOT_FOUND404

    含义
    当前 App 与环境里没有这个对象

  • CONFLICT409

    含义
    与已有数据冲突（例如同一 eventId 内容不同）

  • PROTOCOL_RETIRED410

    含义
    请求的 SDK 协议已结束支持，请按迁移指南升级

  • PAYLOAD_TOO_LARGE413

    含义
    请求体超过 16 KiB

  • RATE_LIMITED429

    含义
    请求频率超出限制，请稍后重试

  • INTERNAL_ERROR500

    含义
    内部失败或响应不符合契约；不返回内部异常细节

  • NOT_CONFIGURED501

    含义
    当前 App 与环境缺少所需集成配置

  • CAPABILITY_UNAVAILABLE501

    含义
    当前运行版本或执行模式尚未开放该操作；重试不会启用能力

  • SERVICE_UNAVAILABLE503

    含义
    服务暂时不可用，请稍后重试
SDK 客户端错误码
code含义
NOT_IDENTIFIED还没有调用 identify 传入客户 Token
INVALID_TOKENToken 为空，或把 gg_sk_ 开头的服务端 Key 传给了浏览器 SDK
SERVER_ONLY在浏览器里创建了服务端客户端
TIMEOUT请求超时（默认 10 秒，可设 1–120,000 毫秒）
NETWORK_ERROR网络请求失败；SDK 不会自动重试
IDENTITY_CHANGED请求进行中切换了客户或调用了 reset，旧响应被丢弃
SCOPE_MISMATCH响应所属的 App 或环境与 SDK 配置的 scope 不一致
INVALID_REQUEST调用参数在本地校验失败
INVALID_RESPONSE服务端响应不符合接口定义
PROTOCOL_MISMATCH服务端响应协议与当前 SDK 不一致，请核对支持范围与版本
HTTP_ERROR服务端返回了无法解析的错误响应
INVALID_URLbaseUrl 不是 HTTPS（本地开发可用 localhost HTTP），或带有凭据、查询参数
INVALID_TIMEOUTtimeoutMs 不在 1–120,000 毫秒之间

SDK 客户端错误码

  • NOT_IDENTIFIED

    含义
    还没有调用 identify 传入客户 Token

  • INVALID_TOKEN

    含义
    Token 为空，或把 gg_sk_ 开头的服务端 Key 传给了浏览器 SDK

  • SERVER_ONLY

    含义
    在浏览器里创建了服务端客户端

  • TIMEOUT

    含义
    请求超时（默认 10 秒，可设 1–120,000 毫秒）

  • NETWORK_ERROR

    含义
    网络请求失败；SDK 不会自动重试

  • IDENTITY_CHANGED

    含义
    请求进行中切换了客户或调用了 reset，旧响应被丢弃

  • SCOPE_MISMATCH

    含义
    响应所属的 App 或环境与 SDK 配置的 scope 不一致

  • INVALID_REQUEST

    含义
    调用参数在本地校验失败

  • INVALID_RESPONSE

    含义
    服务端响应不符合接口定义

  • PROTOCOL_MISMATCH

    含义
    服务端响应协议与当前 SDK 不一致，请核对支持范围与版本

  • HTTP_ERROR

    含义
    服务端返回了无法解析的错误响应

  • INVALID_URL

    含义
    baseUrl 不是 HTTPS（本地开发可用 localhost HTTP），或带有凭据、查询参数

  • INVALID_TIMEOUT

    含义
    timeoutMs 不在 1–120,000 毫秒之间
记录错误码、HTTP 状态和诊断 requestId。retry_same_request 表示按 Retry-After 等待后，用原业务幂等键和原输入重试；reload_state 表示先读取当前状态；recover_operation 表示结果可能未知，先恢复原操作，不能直接再发起一次支付。诊断 requestId 与业务幂等键分别记录。SDK 不自动重试写操作；不要记录任何凭据或商店证明。

读取错误响应

以下字段适用于源码协议 0.5。SDK 版本要求、发布状态与 HTTP 接入方式见版本说明。

相关:版本与接入方式

error.jsonJSON
{  "requestId": "<diagnostic-request-id>",  "error": {    "code": "CONFLICT",    "message": "The original request is still in progress.",    "retryable": true,    "recovery": "retry_same_request",    "retryAfterSeconds": 3,    "reason": "OPERATION_IN_PROGRESS"  }}

上例对应 HTTP 425，Retry-After: 3，且 X-Request-Id 与响应 requestId 一致。message 用于展示；代码分支读取 code 与 recovery。reason 可缺省，不要从 message 推断。retryAfterSeconds 仅在可重试且有等待信息时提供。CLI JSON 输出的 requestId 位于 error 内。

同一错误码的状态区别
HTTPcode处理
501NOT_CONFIGURED / CAPABILITY_UNAVAILABLE前者需要补配置；后者是当前运行时能力未开放，补凭据不会启用它。
409 / 412CONFLICT检查冲突或读取最新状态；不能仅凭 code 判定可重试。普通状态变更通常归一为 409，部分管理转发保留 412。
425CONFLICT原请求仍在处理；等待后重用原身份与输入。
429RATE_LIMITED按等待信息退避，不新建业务操作。
408 / 502 / 503 / 504SERVICE_UNAVAILABLE依 retryable / recovery 处理；RESULT_UNKNOWN 即使为 503 也不可直接重试，须先恢复原操作。无可读错误体时，SDK 可能返回 HTTP_ERROR。
500INTERNAL_ERROR不证明操作已回滚；先读取或恢复原操作。

同一错误码的状态区别

  • 501

    code
    NOT_CONFIGURED / CAPABILITY_UNAVAILABLE
    处理
    前者需要补配置；后者是当前运行时能力未开放，补凭据不会启用它。

  • 409 / 412

    code
    CONFLICT
    处理
    检查冲突或读取最新状态；不能仅凭 code 判定可重试。普通状态变更通常归一为 409，部分管理转发保留 412。

  • 425

    code
    CONFLICT
    处理
    原请求仍在处理；等待后重用原身份与输入。

  • 429

    code
    RATE_LIMITED
    处理
    按等待信息退避，不新建业务操作。

  • 408 / 502 / 503 / 504

    code
    SERVICE_UNAVAILABLE
    处理
    依 retryable / recovery 处理；RESULT_UNKNOWN 即使为 503 也不可直接重试，须先恢复原操作。无可读错误体时，SDK 可能返回 HTTP_ERROR。

  • 500

    code
    INTERNAL_ERROR
    处理
    不证明操作已回滚；先读取或恢复原操作。

恢复动作完整表

按 recovery 选择下一步
recovery下一步
fix_request修正请求参数，不要原样反复提交。
authenticate通过宿主后端恢复当前身份的凭据；不要更换 Customer 来绕过失败。
check_permissions核对当前角色、授权和操作权限。
check_scope核对凭据绑定的 App 与环境。
resolve_conflict检查请求与已有状态的冲突；409 不代表可以直接重试。
reload_state读取当前版本，重新确认修改后再提交。
retry_same_request按 Retry-After 等待；使用原业务幂等键和完全相同的输入，不创建新操作。
configure_integration先完成当前 App 与环境的集成配置；重复请求不会启用能力。
check_availability核对 capabilities 与当前支持范围；未开放操作不能靠重试完成。
upgrade_sdk核对服务端支持的协议与 SDK 版本，按发布说明升级。
recover_operation结果可能未知；用保存的业务操作 ID 查询或恢复原操作，再决定下一步，尤其不要直接再支付一次。
contact_support保留错误码、HTTP 状态和诊断 requestId，联系管理员或支持人员。

按 recovery 选择下一步

  • fix_request

    下一步
    修正请求参数，不要原样反复提交。

  • authenticate

    下一步
    通过宿主后端恢复当前身份的凭据；不要更换 Customer 来绕过失败。

  • check_permissions

    下一步
    核对当前角色、授权和操作权限。

  • check_scope

    下一步
    核对凭据绑定的 App 与环境。

  • resolve_conflict

    下一步
    检查请求与已有状态的冲突；409 不代表可以直接重试。

  • reload_state

    下一步
    读取当前版本，重新确认修改后再提交。

  • retry_same_request

    下一步
    按 Retry-After 等待；使用原业务幂等键和完全相同的输入，不创建新操作。

  • configure_integration

    下一步
    先完成当前 App 与环境的集成配置；重复请求不会启用能力。

  • check_availability

    下一步
    核对 capabilities 与当前支持范围；未开放操作不能靠重试完成。

  • upgrade_sdk

    下一步
    核对服务端支持的协议与 SDK 版本，按发布说明升级。

  • recover_operation

    下一步
    结果可能未知；用保存的业务操作 ID 查询或恢复原操作，再决定下一步，尤其不要直接再支付一次。

  • contact_support

    下一步
    保留错误码、HTTP 状态和诊断 requestId，联系管理员或支持人员。
retryable=true 不表示 SDK 或 CLI 会自动重发，也不允许更换幂等键。TIMEOUT、NETWORK_ERROR、不可读响应和通用 500 不能证明写入失败；诊断 requestId 与业务 requestId / eventId / idempotencyKey 必须分别记录。

业务原因

可选 reason 的安全分类
reason处理
CAPABILITY_NOT_ENABLED当前运行时未开放该操作；核对支持范围。
INTEGRATION_MISSING先完成当前 App 与环境的集成配置。
PROVIDER_CREDENTIAL_REJECTED服务提供方凭据不可用；按 recovery 检查配置或恢复暂时故障。
PRICE_BINDING_REQUIRED修正 Product / Price 的服务提供方绑定或计费配置。
IDEMPOTENCY_CONFLICT已有操作使用了该幂等身份；检查原输入与结果。
RESULT_UNKNOWN原操作可能已生效；先查询或恢复，不直接重发写入。
STATE_CHANGED状态或版本已变化；读取当前状态后重新确认。
OPERATION_IN_PROGRESS原操作或其服务提供方记录仍在处理；按等待信息恢复同一操作。
FUNNEL_VERSION_RETIRED该 Funnel Version 使用已停用的格式，不能再启动或继续运行；在控制台发布新 Version。

可选 reason 的安全分类

  • CAPABILITY_NOT_ENABLED

    处理
    当前运行时未开放该操作；核对支持范围。

  • INTEGRATION_MISSING

    处理
    先完成当前 App 与环境的集成配置。

  • PROVIDER_CREDENTIAL_REJECTED

    处理
    服务提供方凭据不可用；按 recovery 检查配置或恢复暂时故障。

  • PRICE_BINDING_REQUIRED

    处理
    修正 Product / Price 的服务提供方绑定或计费配置。

  • IDEMPOTENCY_CONFLICT

    处理
    已有操作使用了该幂等身份；检查原输入与结果。

  • RESULT_UNKNOWN

    处理
    原操作可能已生效；先查询或恢复，不直接重发写入。

  • STATE_CHANGED

    处理
    状态或版本已变化；读取当前状态后重新确认。

  • OPERATION_IN_PROGRESS

    处理
    原操作或其服务提供方记录仍在处理；按等待信息恢复同一操作。

  • FUNNEL_VERSION_RETIRED

    处理
    该 Funnel Version 使用已停用的格式，不能再启动或继续运行；在控制台发布新 Version。

SDK 错误记录示例

error-reference.tsTypeScript
import { IndianaError } from "@tinkerlandai/indiana-sdk"; // Call from your catch block. Log references, never error.message or credentials.export function errorReference(error: unknown) {  if (!(error instanceof IndianaError)) {    return { code: "UNKNOWN_ERROR", retryable: false, recovery: "contact_support" };  }  return {    code: error.code,    status: error.status,    requestId: error.requestId,    retryable: error.retryable,    recovery: error.recovery,    retryAfterSeconds: error.retryAfterSeconds,    reason: error.reason,  };}// Before retrying a write, use your persisted business operation ID to recover it.// The diagnostic requestId above identifies an HTTP attempt, not its business effect.

相关:CLI 错误与退出码