API error codes

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, gacha and settlement, marketplace or 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 can return either of these JSON bodies. If the catalog is busy, wait for the interval in Retry-After when present.

{
  "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.

{
  "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 · `pull_failed`	Read `data.code` and `data.message`. Payment may already be confirmed. Use the funding hash to recover the draw.
Pull submission or polling · `FAILED`	The buyer was never charged. Look up `error.code` in Failures after submission.
Buyback status · `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	HTTP `200` can return `failed` or `missing_information`. Read `status` and `detail` before requesting shipping rates.
Checkout status	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 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.

Getting started

Gacha

Marketplace

Wallet collections

Redeem and shipping

Developer resources

Partner integrations