> ## 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 error codes

> Look up a v2 error code, check how it was returned and decide when it is safe to retry.

Start with the response’s `Content-Type`. For JSON, read `code` and the endpoint’s documented text field (`error` or `message`). Use the code to choose a recovery action and keep a fallback for an unfamiliar code. Messages may vary. Braces in an endpoint’s response text mark values filled in for each request.

If you already have a code, jump to [authentication and requests](#authentication-and-request-errors), [gacha and settlement](#gacha-funding-and-settlement), [marketplace](#marketplace-orders) or [redemption](#physical-redemption).

Use the HTTP status and machine-readable `code` to choose a recovery action. The text in `error` or `message` can vary. On a successful HTTP response, inspect the operation’s `status` or stream event first.

## Two ways to get HTTP 429

[List pack contents](https://docs.renaiss.xyz/api-reference/gacha/list-pack-contents.md) can return either of these JSON bodies. If the catalog is busy, wait for the interval in `Retry-After` when present.

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

If the builder key has reached its request limit, reduce the request rate for that key.

```json theme={null}
{
  "code": "API_AUTH_RATE_LIMITED",
  "error": "Authentication rate limit exceeded"
}
```

When you contact Renaiss about a failure, include the HTTP status, error code and the `x-request-id` response header. For an accepted pull or buyback, also include the `requestId` returned in the response body.

## Responses without a code

Check `Content-Type` before parsing the body. A plain-text error has no JSON code.

| Response | Where it can occur | How to handle it |
| - | - | - |
| 400 · `Malformed JSON in request body` | Wallet authentication, Gacha and Marketplace writes with malformed JSON | Fix the JSON before resending. |
| 413 · `Payload Too Large` | Marketplace writes above 16 KiB | Reduce the body size. This check can run before authentication. |
| 500 · `Internal Server Error` | An unhandled Wallet Auth, Marketplace or Users failure | Check the inputs, including decimal token IDs. Reconcile a submitted operation before retrying. |

| JSON body limit | If the request exceeds it |
| - | - |
| Wallet Auth · 12 KiB | HTTP `400` with `API_AUTH_INVALID_INPUT`. |
| Gacha · 16 KiB | HTTP `400` with `API_AUTH_INVALID_INPUT`. |
| Redeem · 16 KiB | `WRONG_REQUEST_PARAMS`. Malformed JSON reaching the Redeem parser can also return HTTP `500` with `FUNCTION_ERROR`. Fix the body before retrying. |

When a throttled catalog read or busy direct buyback returns `Retry-After`, wait the number of seconds shown.

## Failures after a request is accepted

| Where the failure appears | What to do |
| - | - |
| [Pull stream](https://docs.renaiss.xyz/api-reference/gacha/stream-pull.md) · `pull_failed` | Read `data.code` and `data.message`. Payment may already be confirmed. Use the funding hash to [recover the draw](https://docs.renaiss.xyz/api-reference/gacha/get-draw.md). |
| Pull submission or polling · `FAILED` | The buyer was never charged. Look up `error.code` in [Failures after submission](https://docs.renaiss.xyz/api-reference/gacha/submit-pull.md#pull-failures). |
| [Buyback status](https://docs.renaiss.xyz/api-reference/gacha/get-buyback-status.md) · `FAILED` | Nothing was bought back. Read `error.code` and `error.message`. If the status stays `PENDING` for more than ten minutes, stop polling and contact Renaiss with the `requestId` before signing again. |
| [Address validation](https://docs.renaiss.xyz/api-reference/redeem/validate-address.md) | HTTP `200` can return `failed` or `missing_information`. Read `status` and `detail` before requesting shipping rates. |
| [Checkout status](https://docs.renaiss.xyz/api-reference/redeem/get-checkout.md) | HTTP `200` can return `submitting` or `failed`. Use the original preparation ID to check the outcome before another payment. |

## Authentication and request errors

| Code | How to handle it |
| - | - |
| `API_AUTH_CREDENTIAL_NOT_ALLOWED` | Remove credentials the route does not accept. Public marketplace reads accept none. |
| `API_AUTH_ERROR` | The authorization service or a chain read failed. For a signed action, check its state before retrying. |
| `API_AUTH_INSUFFICIENT_SCOPE` | The wallet access token lacks the scope this route needs: `redeem:read` to read, `redeem:write` to change. Have the wallet sign in again and ask for the scope. |
| `API_AUTH_INTEGRATION_MISMATCH` | The wallet access token was issued to another builder than the key. Use the key of the builder that issued the token. |
| `API_AUTH_INVALID_ACTION` | Check the wallet, signed data and deadline. If a fresh valid signature is still refused, contact Renaiss with `x-request-id`. |
| `API_AUTH_INVALID_CREDENTIAL` | Check the key or token. For a public marketplace read, remove credentials. For an expired wallet session, refresh or verify again. |
| `API_AUTH_INVALID_INPUT` | Check the payload size, field formats and registered signing context for this endpoint. |
| `API_AUTH_MISSING_CREDENTIAL` | Send the credentials required by this route. Redeem requires both the builder key and the wallet access token. |
| `API_AUTH_RATE_LIMITED` | The builder key hit its rate limit. Wait a little, then retry at a lower rate. |
| `API_AUTH_SUBJECT_MISMATCH` | The wallet access token is not for the chain of this API. Have the wallet sign in again for the right chain. |
| `FUNCTION_ERROR` | Read the response and check the original operation before retrying a write. A Redeem JSON parser failure can also return this code. |
| `GACHA_V3_BUILDER_NOT_ACCEPTED_ON_PUBLIC_API` | This builder key cannot be used on this API. Do not retry; contact Renaiss. |
| `INVALID_SCHEMA` | Invalid schema |
| `SUBGRAPH_RATE_LIMITED` | Too many requests right now. Retry after a short wait. |
| `UNAUTHORIZED` | Use the wallet that owns the collectible for this operation. |
| `WRONG_REQUEST_PARAMS` | Check the field named in the response, including its type, format, allowed values and ownership requirements. |

## Gacha, funding and settlement

| Code | How to handle it |
| - | - |
| `CARD_PACK_NOT_ACTIVE` | The pack is not on sale. Do not retry; show the pack as unavailable. |
| `CARD_PACKS_QUERY_FAILED` | Retry the pack list after a short wait. If it keeps failing, contact Renaiss with the request ID. |
| `CARD_PACK_NOT_FOUND` | On a pull stream, check `fundingConfirmed`. Recover an already paid draw using `permitFundTxHash`. |
| `CONTRACT_REVERT` | Check the operation status and transaction before another payment. A failed stream event can follow a confirmed payment. |
| `CONTRACT_WALLET_CANNOT_RECEIVE_NFT` | The wallet is a contract that cannot receive the collectible. Use a wallet that can receive collectibles. |
| `EOA_PURCHASE_REJECTED` | Use the route and message to distinguish an ineligible wallet, invalid deadline or missing purchase. Reconcile an existing payment before signing again. |
| `GACHA_V3_BUYBACK_EXPIRED` | No tier pays for a collectible now (window closed or a zero-percent hold). Read `GET /v2/gacha/buyback/offers` again and retry only the collectibles it returns. |
| `GACHA_V3_BUYBACK_PRICE_CHANGED` | The signed amount is not the price now: a buyback tier ended after you read the offers. Read `GET /v2/gacha/buyback/offers` again and sign the new amount. |
| `GACHA_V3_BUYBACK_VERIFY_FAILED` | The wallet does not own a collectible in the request. Read `GET /v2/gacha/buyback/offers` and sign only the collectibles it returns. |
| `GACHA_V3_CHECKOUT_ALREADY_PROCESSED` | Check the original pull or current buyback offers before sending another request. |
| `GACHA_V3_CHECKOUT_REQUEST_MISMATCH` | The signed pull differs from an earlier pull with the same wallet and nonce. Check the original pull status or wallet pull history before you sign again. |
| `GACHA_V3_DRAW_RECORD_NOT_FOUND` | A settlement ID could not be found for this pack. Refresh the offers and sign only the settlement IDs returned for that pack. |
| `GACHA_V3_DRAW_REVEAL_FAILED` | The collectible details could not be loaded. The payment was confirmed. Do not pull again: read `GET /v2/gacha/draw-status` with the funding transaction hash. |
| `GACHA_V3_DRAW_UPDATES_UNAVAILABLE` | Live updates are not available. The payment was confirmed. Do not pull again: read `GET /v2/gacha/draw-status` with the funding transaction hash. |
| `GACHA_V3_NOT_ENOUGH_CARDS_IN_SET` | The pack has fewer collectibles left than you asked for. Try a smaller quantity or try again later. |
| `GACHA_V3_NO_SELLABLE_LINEUP` | The pack has no collectibles ready to sell. Try again later. |
| `GACHA_V3_PRICE_MISMATCH` | The pack price changed after you prepared the pull. Prepare again and sign the new data. |
| `GACHA_V3_RESOLVE_DRAWS_FAILED` | The collectibles could not be assigned yet. The payment was confirmed. Do not pull again: read `GET /v2/gacha/draw-status` with the funding transaction hash. |
| `GACHA_V3_STREAM_TIMEOUT` | The stream ran for 90 seconds without a result. The payment may still be going through. |
| `GACHA_V3_TOKEN_STATUS_INVALID` | A collectible in the request was already sold back or sent to the wallet. Read `GET /v2/gacha/buyback/offers` and sign again for the collectibles that are still offered. |
| `INSUFFICIENT_ALLOWANCE` | Check the token and Permit2 spender for the selected network. Approve the required USDT amount and wait for confirmation. |
| `INSUFFICIENT_USDT_AMOUNT` | For a pull or redemption fee, check the USDT balance and the Permit2 allowance. For a buyback the wallet receives USDT. |
| `OP_WALLET_BUSY` | Wait before resending the existing signed request. When the direct buyback response includes Retry-After, wait that many seconds. |
| `PERMIT2_NONCE_ALREADY_USED` | Check the original signed operation and wallet history before signing again. |
| `PERMIT_DEADLINE_TOO_FAR` | The permit deadline is too far ahead. Prepare a new pull and sign it again. |
| `PERMIT_EXPIRED` | The signed pull expired before it was sent, so no payment was made. You can prepare a new pull and sign it again. |
| `PERPETUAL_GACHA_PACK_NOT_FOUND` | The pack could not be found. Refresh the offers and check the pack ID. |
| `PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED` | The signed token is not USDT. Prepare the buyback again from the offers list. |
| `PERPETUAL_GACHA_SUBPACK_RECORD_NOT_FOUND` | A [direct buyback](https://docs.renaiss.xyz/api-reference/gacha/settle-buyback.md) can return this after the transaction confirms. Check the wallet’s activity and current offers before signing again. |
| `PULL_NOT_STARTED` | The connection of the stream closed before the pull started, so no payment was made. Send the same signed pull again. |
| `REQUEST_NOT_FOUND` | The request id is unknown, was made with another builder key, or is a request of the other kind. Check the id returned by the `POST` that created it. |

## Marketplace orders

| Code | How to handle it |
| - | - |
| `ASK_AMOUNT_NOT_POSITIVE` | The price is zero. Send a price above zero. |
| `ASK_HAS_ALREADY_EXPIRED` | Refresh the listing or prepare a new authorization, depending on which side of the trade expired. |
| `ASK_TOKEN_ID_MISMATCH` | Check that the submitted `tokenId` identifies the same card as `askData.tokenId`. Copy both from the same prepare response. If the seller chose a different card, prepare and sign a new ask. |
| `BID_AUTHORIZATION_ALREADY_USED` | This signed bid was already submitted. Check the collectible and the wallet's orders first: the earlier bid may be active, cancelled or already filled. Sign a new bid only if you still want one. |
| `BID_BELOW_MINIMUM` | The bid is below the smallest bid allowed. Prepare again with a higher amount. |
| `BID_HAS_ALREADY_EXPIRED` | Refresh the bid or prepare a fresh authorization for the buyer. |
| `BID_INSUFFICIENT_BALANCE` | The wallet holds less USDT than the bid. Add funds or bid less. |
| `BID_LOWER_THAN_ASK` | The amount you signed is lower than the listing price. Prepare again and sign the new data. |
| `BID_TOKEN_ID_MISMATCH` | Check that the submitted `tokenId` identifies the same card as `bidData.tokenId`. If you are accepting an existing bid, refresh the order book and select a bid for that card. |
| `COLLECTIBLE_NOT_FOUND` | The token id is unknown or the collectible is not available on this API. Check the token id. Do not retry with the same id. |
| `COLLECTIBLE_ONCHAIN_OWNER_MISMATCH` | The wallet does not own the collectible. Use the wallet that owns it. |
| `INVALID_ASK_SIGNATURE` | The signature on the listing was not accepted. Prepare again and have the wallet sign the new data. |
| `INVALID_BID_FEE_BPS` | The fee in the signed bid is not accepted. Prepare again and sign the new data. |
| `INVALID_BID_SIGNATURE` | The signature on the bid was not accepted. Prepare again and have the wallet sign the new data. |
| `INVALID_OFFER_STATUS` | The bid is no longer active, has expired or was already used. Read the bids again; do not retry this request. |
| `INVALID_OFFER_TYPE` | The order you sent is not a bid. Read the bids again; do not retry this request. |
| `MATCHING_ASK_NOT_FOUND` | The collectible has no active listing. Read the listings again; do not retry this request. |
| `MATCHING_ASK_PERMIT_NOT_FOUND` | The listing cannot be bought. Read the listings again; do not retry this request. |
| `MATCHING_BID_PERMIT_NOT_FOUND` | The bid cannot be accepted. Read the bids again; do not retry this request. |
| `OFFER_EXPIRY_TOO_LONG` | The listing expires too far from now. Prepare again with a shorter expiry. |
| `OFFER_NOT_FOUND` | The bid does not exist. Read the bids again; do not retry this request. |
| `ORDER_NOT_FOUND` | Refresh the order book or wallet orders. Check the order ID and whether it is still active. |
| `TOO_MANY_ACTIVE_BIDS` | The wallet already has the most active bids it can hold. Cancel a bid first. |

## Physical redemption

| Code | How to handle it |
| - | - |
| `REDEEM_ADDRESS_VALIDATION_API_ERROR` | The address check did not give an answer. Try again later. |
| `REDEEM_COURIER_RATES_FETCH_FAILED` | Shipping rates could not be fetched for this cart and destination. Check the address, or try again later. |
| `REDEMPTION_ORDER_CHECKOUT_STILL_ACTIVE` | A checkout for these collectibles is already in progress. Do not send it again. Read `GET /v2/redeem/checkout/{preparationId}` to follow it. |
| `REDEMPTION_ORDER_NOT_FOUND` | Check the request or preparation ID and wallet. If a quote or preparation expired, obtain a new quote. |
| `REDEMPTION_ORDER_VALIDATION_FAILED` | The prepared redemption is no longer valid. Prepare again from a new quote. |
| `REDEMPTION_VAULT_RESOLUTION_FAILED` | Shipping could not be priced for these collectibles right now. Retry later. |


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