> ## Documentation Index
> Fetch the complete documentation index at: https://docs.renaiss.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# API 错误码

> 按 v2 错误码查找原因，区分 HTTP 错误和提交后的失败，并选择正确的恢复方式。

先查看响应的 `Content-Type`。如果是 JSON，读取 `code` 和接口指定的文本字段（`error` 或 `message`）。根据错误码选择处理方式，并为未知错误码保留默认处理逻辑。接口页面中的响应文本是示例，花括号内为运行时填入的值。

如果已拿到错误码，可直接查阅[身份验证与请求](#身份验证与请求错误)、[抽卡与结算](#抽卡、付款与结算)、[市场](#市场订单)或[实物兑换](#实物兑换)。

请根据 HTTP 状态和机器可读的 `code` 选择处理方式。`error` 或 `message` 中的文本可能变化。HTTP 请求成功时，请先查看操作的 `status` 或事件流中的事件。

## 同一接口的两种 HTTP 429 响应

[查询卡包内容](https://docs.renaiss.xyz/cn/api-reference/gacha/list-pack-contents.md)可能返回以下两种 JSON 响应。如果卡包目录查询触发限流，且响应含有 `Retry-After`，请按指定秒数等待后再重试。

```json theme={null}
{
  "code": "SUBGRAPH_RATE_LIMITED",
  "message": "Unable to load pack content"
}
```

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

```json theme={null}
{
  "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`，请等待其中指定的秒数。

## 请求受理后的失败

| 在哪里看到失败 | 如何处理 |
| - | - |
| [抽卡事件流](https://docs.renaiss.xyz/cn/api-reference/gacha/stream-pull.md) · `pull_failed` | 读取 `data.code` 和 `data.message`。付款可能已确认，可用付款哈希[找回抽卡结果](https://docs.renaiss.xyz/cn/api-reference/gacha/get-draw.md)。 |
| 提交抽卡或查询抽卡状态 · `FAILED` | 买家未被扣款。根据 `error.code` 查阅[提交后的失败](https://docs.renaiss.xyz/cn/api-reference/gacha/submit-pull.md#pull-failures)。 |
| [回购状态](https://docs.renaiss.xyz/cn/api-reference/gacha/get-buyback-status.md) · `FAILED` | 该请求未回购任何卡牌。读取 `error.code` 和 `error.message`。若状态持续为 `PENDING` 超过十分钟，请停止轮询，携原 `requestId` 联系 Renaiss 后再决定是否重新签名。 |
| [地址验证](https://docs.renaiss.xyz/cn/api-reference/redeem/validate-address.md) | HTTP `200` 仍可能返回 `failed` 或 `missing_information`。请查看 `status` 和 `detail` 后再查询运费。 |
| [结账状态](https://docs.renaiss.xyz/cn/api-reference/redeem/get-checkout.md) | 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` | [直接回购](https://docs.renaiss.xyz/cn/api-reference/gacha/settle-buyback.md)可能在交易确认后返回此码。再次签名前请先核对钱包活动和当前报价。 |
| `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` | 当前无法为这些藏品计算运费，请稍后重试。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.