API 错误码

先查看响应的 Content-Type。如果是 JSON，读取 code 和接口指定的文本字段（error 或 message）。根据错误码选择处理方式，并为未知错误码保留默认处理逻辑。接口页面中的响应文本是示例，花括号内为运行时填入的值。如果已拿到错误码，可直接查阅身份验证与请求、抽卡与结算、市场或实物兑换。请根据 HTTP 状态和机器可读的 code 选择处理方式。error 或 message 中的文本可能变化。HTTP 请求成功时，请先查看操作的 status 或事件流中的事件。

同一接口的两种 HTTP 429 响应

查询卡包内容可能返回以下两种 JSON 响应。如果卡包目录查询触发限流，且响应含有 Retry-After，请按指定秒数等待后再重试。

{
  "code": "SUBGRAPH_RATE_LIMITED",
  "message": "Unable to load pack content"
}

如果是开发者密钥达到请求上限，请降低该密钥的请求频率。

{
  "code": "API_AUTH_RATE_LIMITED",
  "error": "Authentication rate limit exceeded"
}

联系 Renaiss 排查问题时，请提供 HTTP 状态、错误码和响应头 x-request-id。如果抽卡或回购请求已受理，请同时提供响应体中的 requestId。

没有错误码的响应

解析响应前检查 Content-Type。纯文本错误没有 JSON 错误码。

响应	可能出现的位置	处理方式
400 · `Malformed JSON in request body`	钱包认证、抽卡或市场写入请求的 JSON 格式错误	修正 JSON 后再提交。
413 · `Payload Too Large`	市场写入请求体超过 16 KiB	缩小请求体。此检查可能先于身份验证。
500 · `Internal Server Error`	钱包认证、市场或 Users 接口发生未处理的异常	检查输入，尤其是十进制代币 ID。写入操作先核对原请求结果，再决定是否重试。

JSON 请求体上限	超限时的响应
钱包认证 · 12 KiB	HTTP `400`，错误码 `API_AUTH_INVALID_INPUT`。
抽卡 · 16 KiB	HTTP `400`，错误码 `API_AUTH_INVALID_INPUT`。
实物兑换 · 16 KiB	错误码 `WRONG_REQUEST_PARAMS`。如果兑换接口收到的 JSON 格式错误，也可能返回 HTTP `500` 和 `FUNCTION_ERROR`。请先修正请求体再重试。

如果目录读取触发限流或直接回购繁忙，且响应带有 Retry-After，请等待其中指定的秒数。

请求受理后的失败

在哪里看到失败	如何处理
抽卡事件流 · `pull_failed`	读取 `data.code` 和 `data.message`。付款可能已确认，可用付款哈希找回抽卡结果。
提交抽卡或查询抽卡状态 · `FAILED`	买家未被扣款。根据 `error.code` 查阅提交后的失败。
回购状态 · `FAILED`	该请求未回购任何卡牌。读取 `error.code` 和 `error.message`。若状态持续为 `PENDING` 超过十分钟，请停止轮询，携原 `requestId` 联系 Renaiss 后再决定是否重新签名。
地址验证	HTTP `200` 仍可能返回 `failed` 或 `missing_information`。请查看 `status` 和 `detail` 后再查询运费。
结账状态	HTTP `200` 可能返回 `submitting` 或 `failed`。再次付款前，先用原准备 ID 查询结果。

身份验证与请求错误

错误码	处理方式
`API_AUTH_CREDENTIAL_NOT_ALLOWED`	移除接口不接受的凭据。公开市场查询请省略全部凭据。
`API_AUTH_ERROR`	授权服务或链上读取失败。已签名操作请先查询状态，再决定是否重试。
`API_AUTH_INSUFFICIENT_SCOPE`	令牌缺少所需权限，读取需 redeem:read，修改需 redeem:write。请钱包重新登录并申请相应权限。
`API_AUTH_INTEGRATION_MISMATCH`	令牌和密钥属于不同开发者。请使用签发令牌的开发者对应的密钥。
`API_AUTH_INVALID_ACTION`	请检查钱包、签名数据和截止时间。若新的有效签名仍被拒绝，请将 `x-request-id` 提供给 Renaiss。
`API_AUTH_INVALID_CREDENTIAL`	核对密钥或令牌。公开市场查询应移除凭据；钱包会话过期时刷新令牌或重新验证。
`API_AUTH_INVALID_INPUT`	核对请求体大小、字段格式，以及该接口要求的已注册签名上下文。
`API_AUTH_MISSING_CREDENTIAL`	请发送该接口要求的凭据。实物兑换同时需要开发者密钥和钱包访问令牌。
`API_AUTH_RATE_LIMITED`	已达到密钥的请求频率上限。稍候再以较低频率重试。
`API_AUTH_SUBJECT_MISMATCH`	令牌所属链与 API 不符。请针对正确的链重新验证钱包。
`FUNCTION_ERROR`	先检查响应及原操作状态，再决定是否重试写入。兑换请求的 JSON 解析失败也可能返回此码。
`GACHA_V3_BUILDER_NOT_ACCEPTED_ON_PUBLIC_API`	此密钥无法用于当前 API。请联系 Renaiss，无需重试。
`INVALID_SCHEMA`	数据结构无效。
`SUBGRAPH_RATE_LIMITED`	当前请求过多，请稍后重试。
`UNAUTHORIZED`	请使用实际持有藏品的钱包执行此操作。
`WRONG_REQUEST_PARAMS`	按响应指出的字段核对类型、格式、取值和所有权要求。

抽卡、付款与结算

错误码	处理方式
`CARD_PACK_NOT_ACTIVE`	卡包未在售，标记为不可购买，无需重试。
`CARD_PACKS_QUERY_FAILED`	稍后重试卡包列表查询。如果持续失败，请提供请求 ID 联系 Renaiss。
`CARD_PACK_NOT_FOUND`	在抽卡事件流中，请读取 `fundingConfirmed`。若已付款，请用 `permitFundTxHash` 找回抽卡结果。
`CONTRACT_REVERT`	再次付款前先核对操作状态和交易。已确认付款后，事件流仍可能报告失败。
`CONTRACT_WALLET_CANNOT_RECEIVE_NFT`	合约钱包无法接收藏品。请使用能够接收藏品的钱包。
`EOA_PURCHASE_REJECTED`	结合接口和消息判断钱包、截止时间或购买记录是否有误。再次签名前先核对原付款。
`GACHA_V3_BUYBACK_EXPIRED`	目前没有可付款档位，可能是窗口已关闭或当前为零比例档。重新获取 `GET /v2/gacha/buyback/offers`，按结果重试。
`GACHA_V3_BUYBACK_PRICE_CHANGED`	读取报价后档位已截止，签名金额与当前价格不符。重新查询 `GET /v2/gacha/buyback/offers` 并签署新金额。
`GACHA_V3_BUYBACK_VERIFY_FAILED`	钱包不持有其中一件藏品。请查询 `GET /v2/gacha/buyback/offers`，仅为返回的藏品签名。
`GACHA_V3_CHECKOUT_ALREADY_PROCESSED`	再次发送前先查询原抽卡请求或最新回购报价。
`GACHA_V3_CHECKOUT_REQUEST_MISMATCH`	相同钱包和 nonce 之前签署的抽卡请求与本次请求不同。再次签名前先查原请求状态或钱包抽卡记录。
`GACHA_V3_DRAW_RECORD_NOT_FOUND`	该卡包中没有对应的结算 ID。刷新报价，并只为该卡包实际返回的结算 ID 签名。
`GACHA_V3_DRAW_REVEAL_FAILED`	暂时无法读取藏品详情，付款已确认。用付款哈希查询 `GET /v2/gacha/draw-status`，不要重复开包。
`GACHA_V3_DRAW_UPDATES_UNAVAILABLE`	无法获得实时更新，付款已确认。请使用付款哈希查询 `GET /v2/gacha/draw-status`，不要重复开包。
`GACHA_V3_NOT_ENOUGH_CARDS_IN_SET`	剩余藏品数量不足，请减少数量或稍后再试。
`GACHA_V3_NO_SELLABLE_LINEUP`	该卡包尚无可出售藏品，请稍后重试。
`GACHA_V3_PRICE_MISMATCH`	准备后卡包价格变化，需要重新准备并签署新数据。
`GACHA_V3_RESOLVE_DRAWS_FAILED`	暂时无法分配藏品，付款已确认。用付款哈希查询 `GET /v2/gacha/draw-status`，不要重复开包。
`GACHA_V3_STREAM_TIMEOUT`	流等待 90 秒仍未获得结果，付款可能仍在进行。
`GACHA_V3_TOKEN_STATUS_INVALID`	藏品已回售或已交付钱包。重新读取 `GET /v2/gacha/buyback/offers`，仅为仍有报价的藏品签名。
`INSUFFICIENT_ALLOWANCE`	核对所选网络的代币和 Permit2 支出方，授权足够的 USDT 并等待确认。
`INSUFFICIENT_USDT_AMOUNT`	抽卡或支付兑换费用时，请核对 USDT 余额和授予 Permit2 的额度。回购时钱包接收 USDT。
`OP_WALLET_BUSY`	稍候再发送原来的签名请求。直接回购返回 Retry-After 时，等待所示秒数。
`PERMIT2_NONCE_ALREADY_USED`	再次签名前查询原签名操作及钱包记录。
`PERMIT_DEADLINE_TOO_FAR`	许可截止时间过远。请重新准备并签署新的抽卡请求。
`PERMIT_EXPIRED`	已签名的请求在发送前过期，未付款。可以重新准备并签名。
`PERPETUAL_GACHA_PACK_NOT_FOUND`	未找到卡包。请刷新报价并核对卡包 ID。
`PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED`	签署的代币不是 USDT。请从报价列表重新准备回购。
`PERPETUAL_GACHA_SUBPACK_RECORD_NOT_FOUND`	直接回购可能在交易确认后返回此码。再次签名前请先核对钱包活动和当前报价。
`PULL_NOT_STARTED`	流在抽卡开始前断开，尚未付款。可以重发同一签名请求。
`REQUEST_NOT_FOUND`	请求 ID 未知、属于其他开发者或其他请求类型。请核对创建请求的 POST 接口返回的 ID。

市场订单

错误码	处理方式
`ASK_AMOUNT_NOT_POSITIVE`	价格为零。请提供大于零的价格。
`ASK_HAS_ALREADY_EXPIRED`	核对到期的是哪一方，刷新挂牌或重新准备并签署授权。
`ASK_TOKEN_ID_MISMATCH`	核对提交的 `tokenId` 与 `askData.tokenId` 是否指向同一张卡牌。两个字段都应取自同一次准备响应。如果卖家选择了另一张卡牌，请重新准备并签署卖单。
`BID_AUTHORIZATION_ALREADY_USED`	买单已提交。先查看藏品和钱包订单，原单可能仍有效、已撤销或已成交。确需另下买单时才重新签名。
`BID_BELOW_MINIMUM`	出价低于最低金额。请提高金额并重新准备。
`BID_HAS_ALREADY_EXPIRED`	刷新买单，或为买家重新准备授权。
`BID_INSUFFICIENT_BALANCE`	钱包的 USDT 不足，请补足余额或降低出价。
`BID_LOWER_THAN_ASK`	签名的出价低于挂牌价。请重新准备并签名。
`BID_TOKEN_ID_MISMATCH`	核对提交的 `tokenId` 与 `bidData.tokenId` 是否指向同一张卡牌。如果是在接受已有买单，请刷新订单簿并选择该卡牌的买单。
`COLLECTIBLE_NOT_FOUND`	代币 ID 未知或藏品在该 API 中不可用。请核对 ID，不要用同一 ID 重试。
`COLLECTIBLE_ONCHAIN_OWNER_MISMATCH`	该钱包不是链上持有人。请使用持有藏品的钱包。
`INVALID_ASK_SIGNATURE`	卖单签名无效。请重新准备并由钱包签署新数据。
`INVALID_BID_FEE_BPS`	签名买单的费率无效。请重新准备并签名。
`INVALID_BID_SIGNATURE`	买单签名无效。请重新准备并让钱包签署新数据。
`INVALID_OFFER_STATUS`	买单已失效、过期或已使用。请刷新买单列表，不要重发原请求。
`INVALID_OFFER_TYPE`	提交的订单不是买单。请刷新买单列表，不要重发原请求。
`MATCHING_ASK_NOT_FOUND`	藏品没有有效挂牌。请刷新挂牌列表，不要重复发送原请求。
`MATCHING_ASK_PERMIT_NOT_FOUND`	该挂牌无法购买。请刷新挂牌列表，不要重复发送原请求。
`MATCHING_BID_PERMIT_NOT_FOUND`	无法接受该买单。请刷新买单列表，不要重发原请求。
`OFFER_EXPIRY_TOO_LONG`	卖单到期时间过远。请缩短有效期并重新准备。
`OFFER_NOT_FOUND`	买单不存在。请刷新买单列表，不要重发原请求。
`ORDER_NOT_FOUND`	刷新订单簿或钱包订单。核对订单 ID 及有效状态。
`TOO_MANY_ACTIVE_BIDS`	钱包已达到有效买单数量上限。请先撤销一笔买单。

实物兑换

错误码	处理方式
`REDEEM_ADDRESS_VALIDATION_API_ERROR`	暂未获取地址验证结果，请稍后重试。
`REDEEM_COURIER_RATES_FETCH_FAILED`	无法获取该购物车和收货地的运费。请核对地址或稍后重试。
`REDEMPTION_ORDER_CHECKOUT_STILL_ACTIVE`	藏品已有进行中的结账，不要重复发送。使用 `GET /v2/redeem/checkout/{preparationId}` 查询进度。
`REDEMPTION_ORDER_NOT_FOUND`	核对请求或准备 ID 以及钱包。若报价或准备记录已过期，请重新报价。
`REDEMPTION_ORDER_VALIDATION_FAILED`	原兑换准备已失效。请重新获取报价并准备。
`REDEMPTION_VAULT_RESOLUTION_FAILED`	当前无法为这些藏品计算运费，请稍后重试。

入门

抽卡

交易市场

钱包收藏

实物兑换与配送

开发资源

合作伙伴接入