> ## 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. # Get buyback status > Check the outcome of a submitted buyback with its `requestId` and the original builder key. Poll about once per second until `COMPLETED` or `FAILED`. The request remains available for at least 30 days. If `PENDING` lasts more than ten minutes, stop polling and contact Renaiss with the original `requestId`. Wait for the outcome before signing another buyback for the same cards. ## Request Builder key required ## Response ### Failures after submission If the HTTP 200 body has `status: "FAILED"`, read `error.code` and `error.message`. A failed request bought nothing back. Refresh the wallet’s offers before signing a replacement. If it stays `PENDING` for more than 10 minutes, stop polling and contact Renaiss with the original `requestId`. Braces in the table mark runtime values. | Code | `error.message` | | - | - | | `GACHA_V3_BUYBACK_SNAPSHOT_NOT_FOUND` `GACHA_V3_SETTLEMENT_ID_MISMATCH` `PERPETUAL_GACHA_BUYBACK_CONFIG_NOT_FOUND` `PERPETUAL_GACHA_VENDING_MACHINE_ADDRESS_NOT_FOUND` | `Internal server error` Contact Renaiss with the original `requestId`. | | `CONTRACT_REVERT` | `Smart contract execution reverted` `Contract error: {reason}` | | `GACHA_V3_BUYBACK_EXPIRED` | `Buyback has expired for {buybackId}` | | `GACHA_V3_BUYBACK_PRICE_CHANGED` | `amount {signedAmount} does not match expected total {expectedTotal}` | | `GACHA_V3_BUYBACK_VERIFY_FAILED` | `Buyer does not own this card` | | `GACHA_V3_DRAW_RECORD_NOT_FOUND` | `Pack draw record not found for buybackId {buybackId}` | | `GACHA_V3_TOKEN_STATUS_INVALID` | `Card is already buyback or released` | | `OP_WALLET_BUSY` | `Payments are busy right now and nothing was charged. Please try again in a few seconds.` Wait a few seconds, then resend the same signed buyback. | | `PERPETUAL_GACHA_PACK_NOT_FOUND` | `Perpetual VRF pack not found: {cardPackId}` | | `PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED` | `Buyback token must be USDT` | ## Error codes Match the HTTP status and response text to a row below. For guidance on codes shared across endpoints, see [Error meanings and recovery](https://docs.renaiss.xyz/api-reference/errors.md). | HTTP | Error code | Text field | Response text and recovery | | :- | :- | :- | :- | | `400` | `WRONG_REQUEST_PARAMS` | `message` | `Bad request - invalid parameters` A field is missing or has the wrong form. Fix the request and send it again. | | `401` | `API_AUTH_INVALID_CREDENTIAL` | `error` | `Invalid authentication credential` The builder key is malformed, unknown, expired or revoked. Check the key. Do not retry with the same key. | | `401` | `API_AUTH_MISSING_CREDENTIAL` | `error` | `Required authentication credential is missing` No builder key was sent. Send your builder key in the `x-builder-api-key` header. | | `403` | `API_AUTH_CREDENTIAL_NOT_ALLOWED` | `error` | `Credential is not allowed by this policy` This route takes a builder key only. Remove the `Authorization` header and any other credential, then send the request again. | | `403` | `GACHA_V3_BUILDER_NOT_ACCEPTED_ON_PUBLIC_API` | `error` | `This builder checks out on its own surface, not on the public API` This builder key cannot be used on this API. Do not retry; contact Renaiss. | | `404` | `REQUEST_NOT_FOUND` | `error` | `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. | | `429` | `API_AUTH_RATE_LIMITED` | `error` | `Authentication rate limit exceeded` The builder key hit its rate limit. Wait a little, then retry at a lower rate. | | `500` | `API_AUTH_ERROR` | `error` | `Internal server error` | | `500` | `FUNCTION_ERROR` | `error` | `Internal server error` | | `500` | Other code | `error` | `Internal server error` | ## OpenAPI ````yaml api-reference/openapi.json GET /v2/gacha/buyback/status openapi: 3.1.1 info: version: 1.0.0 title: Renaiss Builder API v2 description: >- Builder API v2 for gacha, marketplace and redemption with external wallets on BNB Smart Chain (chain 56). Any active, approved builder key can prepare purchases. A collectible is an item a wallet can pull, trade, sell back or redeem, such as a card. This API calls every such item a collectible (e.g. cards), in paths, fields and descriptions. Browse publicly, then prepare and sign actions with the buyer wallet. Gacha history and buyback offers require your builder key; purchases and buybacks also require a wallet action signature. Private shipping data and redemption require a wallet access token, which the API issues from a registered partner origin after the wallet signs a sign-in message. Gacha and marketplace never use a wallet access token. Keep the builder key on your backend. The acting wallet is an EOA or a deployed ERC-1271 contract account. EIP-7702 delegated accounts, ERC-6492 and ERC-8010 wrapped signatures and Renaiss-managed Safes are refused (a Safe only after its signature verified). A pull to a contract account that cannot receive ERC-721 tokens returns `CONTRACT_WALLET_CANNOT_RECEIVE_NFT`. A failed chain read returns `API_AUTH_ERROR` (500). Wallet access tokens and redemption are EOA only. servers: - url: https://api.renaiss.xyz description: BNB Smart Chain - url: https://dev-api.renaiss.xyz description: BNB testnet security: [] tags: - name: Gacha v2 description: >- Direct-EOA pack browsing, purchases, collectible (e.g. card) reveals, purchase history and buybacks. Start here; no wallet access token is needed. - name: Marketplace description: >- Public collectible (e.g. card) browsing and external-wallet asks, bids, purchases and cancellations. Trading requires builder authorization and wallet action signatures. - name: Users description: >- What one wallet address has and did: its collectibles (e.g. cards), their total market value and its activities. The whole wallet, whichever builder it used. Requires your builder key only. - name: Redemption description: >- Shipping eligibility, quotes, redemption preparation, submission and tracking. Requires your builder key and a wallet access token for the same wallet. - name: Wallet access tokens description: >- Get, refresh and revoke the wallet access tokens that Redeem needs. The wallet signs a sign-in message (valid 5 minutes, one use); the API returns a wallet access token (15 minutes) and a refresh token (7 days, single use). Register exact partner frontend origins with Renaiss before use. Gacha and marketplace never use a wallet access token. paths: /v2/gacha/buyback/status: get: tags: - Gacha v2 summary: Get the status of a buyback by its requestId description: >- Check the outcome of a submitted buyback with its `requestId` and the original builder key. parameters: - schema: type: string format: uuid required: true name: requestId in: query responses: '200': description: Success content: application/json: schema: type: object properties: requestId: type: string format: uuid status: type: string enum: - PENDING - COMPLETED - FAILED description: >- `PENDING`: in progress. `COMPLETED`: settled on chain. `FAILED`: nothing was bought back. buyerWalletAddress: type: string description: >- 20-byte, 0x-prefixed wallet or contract address. Use lowercase or a valid checksum. cardPackId: type: string format: uuid settlementIds: type: array items: type: string description: >- 32 bytes encoded as 0x followed by 64 hexadecimal digits. txHash: type: - string - 'null' description: The buyback transaction hash. Null unless `COMPLETED`. totalAmountInUsdt: type: - string - 'null' pattern: ^\d+$ description: USDT paid, with 18 decimals. Null unless `COMPLETED`. itemCount: type: - integer - 'null' exclusiveMinimum: 0 description: >- How many collectibles were bought back. Null unless `COMPLETED`. error: type: - object - 'null' properties: code: type: string description: Why the request failed. examples: - PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED - GACHA_V3_TOKEN_STATUS_INVALID - GACHA_V3_BUYBACK_VERIFY_FAILED - GACHA_V3_BUYBACK_EXPIRED - CONTRACT_REVERT - PERPETUAL_GACHA_PACK_NOT_FOUND - GACHA_V3_DRAW_RECORD_NOT_FOUND - GACHA_V3_BUYBACK_PRICE_CHANGED - OP_WALLET_BUSY message: type: string description: A short sentence about what went wrong. required: - code - message description: >- Why the request failed: `{ code, message }`. Null unless the status is `FAILED`. A `FAILED` buyback bought nothing back. The codes and sentences are those of `POST /v2/gacha/buyback`. The `code` is a plain string, so new codes can appear. What to do for each: - `PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED`: the signed token is not USDT. Prepare the buyback again from the offers list. - `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. - `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_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. - `CONTRACT_REVERT`: the buyback was rejected. Read `GET /v2/gacha/buyback/offers` to see which collectibles are still offered, then sign again. - `PERPETUAL_GACHA_PACK_NOT_FOUND`: the pack could not be found. Refresh the offers and check the pack ID. - `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_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. - `OP_WALLET_BUSY`: every payment sender is busy. Retry the request. Send the same signed buyback again after a few seconds. - Any other code: read `GET /v2/gacha/buyback/offers` before you send the request again. A buyback whose transaction may already have been sent (for example a confirmation that timed out, or a rejection at the send) is not marked `FAILED`: it stays `PENDING` until it is reconciled. required: - requestId - status - buyerWalletAddress - cardPackId - settlementIds - txHash - totalAmountInUsdt - itemCount - error examples: PENDING: summary: The buyback is in progress. value: requestId: b81d0f7e-2c4a-4d6b-8e13-5a9c7d1f3b20 buyerWalletAddress: '0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2' cardPackId: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13 settlementIds: - >- 0x2222222222222222222222222222222222222222222222222222222222222222 status: PENDING txHash: null totalAmountInUsdt: null itemCount: null error: null COMPLETED: summary: The buyback is settled. value: requestId: b81d0f7e-2c4a-4d6b-8e13-5a9c7d1f3b20 buyerWalletAddress: '0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2' cardPackId: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13 settlementIds: - >- 0x2222222222222222222222222222222222222222222222222222222222222222 status: COMPLETED txHash: >- 0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc totalAmountInUsdt: '39141000000000000000' itemCount: 1 error: null FAILED: summary: The buyback failed and nothing was bought back. value: requestId: b81d0f7e-2c4a-4d6b-8e13-5a9c7d1f3b20 buyerWalletAddress: '0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2' cardPackId: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13 settlementIds: - >- 0x2222222222222222222222222222222222222222222222222222222222222222 status: FAILED txHash: null totalAmountInUsdt: null itemCount: null error: code: GACHA_V3_TOKEN_STATUS_INVALID message: Card is already buyback or released '400': description: >- The request was refused before anything happened. See [error codes and recovery](/api-reference/gacha/get-buyback-status#http-errors). content: application/json: schema: type: object properties: code: type: string enum: - WRONG_REQUEST_PARAMS message: type: string description: A short sentence about what went wrong. required: - code - message example: code: WRONG_REQUEST_PARAMS message: Bad request - invalid parameters '401': description: >- The builder key is missing or not accepted. See [error codes and recovery](/api-reference/gacha/get-buyback-status#http-errors). content: application/json: schema: type: object properties: error: type: string description: A short sentence about what went wrong. code: type: string enum: - API_AUTH_MISSING_CREDENTIAL - API_AUTH_INVALID_CREDENTIAL required: - error - code example: error: Required authentication credential is missing code: API_AUTH_MISSING_CREDENTIAL '403': description: >- The builder key is not allowed to make this request. See [error codes and recovery](/api-reference/gacha/get-buyback-status#http-errors). content: application/json: schema: type: object properties: error: type: string description: A short sentence about what went wrong. code: type: string enum: - API_AUTH_CREDENTIAL_NOT_ALLOWED - GACHA_V3_BUILDER_NOT_ACCEPTED_ON_PUBLIC_API required: - error - code example: error: Credential is not allowed by this policy code: API_AUTH_CREDENTIAL_NOT_ALLOWED '404': description: >- No such request. See [error codes and recovery](/api-reference/gacha/get-buyback-status#http-errors). content: application/json: schema: type: object properties: error: type: string description: A short sentence about what went wrong. code: type: string enum: - REQUEST_NOT_FOUND required: - error - code example: error: Request not found code: REQUEST_NOT_FOUND '429': description: >- Too many requests with this builder key. See [error codes and recovery](/api-reference/gacha/get-buyback-status#http-errors). content: application/json: schema: type: object properties: error: type: string description: A short sentence about what went wrong. code: type: string enum: - API_AUTH_RATE_LIMITED required: - error - code example: error: Authentication rate limit exceeded code: API_AUTH_RATE_LIMITED '500': description: >- A failure on our side. Retry later. See [error codes and recovery](/api-reference/gacha/get-buyback-status#http-errors). content: application/json: schema: type: object properties: error: type: string description: A short sentence about what went wrong. code: type: string required: - error - code example: error: Internal server error code: FUNCTION_ERROR security: - builderAuth: [] components: securitySchemes: builderAuth: type: apiKey in: header name: x-builder-api-key description: >- Your approved builder API key. Keep it on your backend. Gacha and marketplace writes also require wallet action signatures. Redeem also needs a wallet access token, a Bearer token the API issues after the wallet signs a sign-in message. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.