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

请求与错误

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

SDK 0.0.1更新于

请求与错误

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

当前 HTTP 接口与权限
方法路径调用方权限
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/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/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/grantserveroffers:grant
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/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/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/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
    调用方
    server
    权限
    offers:grant

  • 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

当前 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

服务端错误码
HTTPcode含义
400INVALID_REQUEST请求体或参数不符合接口定义
401UNAUTHENTICATED缺少、无效、过期或已撤销的凭据
403FORBIDDEN权限不足，或浏览器来源不在允许列表
403SCOPE_MISMATCH校验头与凭据所属 App / 环境不一致
404NOT_FOUND当前 App 与环境里没有这个对象
409CONFLICT与已有数据冲突（例如同一 eventId 内容不同）
413PAYLOAD_TOO_LARGE请求体超过 16 KiB
429RATE_LIMITED请求频率超出限制，请稍后重试
500INTERNAL_ERROR内部失败或响应不符合契约；不返回内部异常细节
501NOT_CONFIGURED该能力未配置或尚未实现
503SERVICE_UNAVAILABLE服务暂时不可用，请稍后重试

服务端错误码

  • INVALID_REQUEST400

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

  • UNAUTHENTICATED401

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

  • FORBIDDEN403

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

  • SCOPE_MISMATCH403

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

  • NOT_FOUND404

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

  • CONFLICT409

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

  • PAYLOAD_TOO_LARGE413

    含义
    请求体超过 16 KiB

  • RATE_LIMITED429

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

  • INTERNAL_ERROR500

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

  • NOT_CONFIGURED501

    含义
    该能力未配置或尚未实现

  • 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服务端响应不符合接口定义
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

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

  • HTTP_ERROR

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

  • INVALID_URL

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

  • INVALID_TIMEOUT

    含义
    timeoutMs 不在 1–120,000 毫秒之间
记录错误码、HTTP 状态和 requestId；不要记录密钥、客户 Token、运行凭据或原生商店证明。