Find the failing step.
Try it first
Recover the original operation#
You need Its saved purchase or attempt key, payment ID and exact environment.
- Record the current state and verification source.
- Match studio, host, game, chain and payer to the original request.
- Retry the appropriate read or resume operation, then inspect the result.
Check your result You recover without creating a duplicate charge, grant or deployment.
Keep the payment ID and purchase key. Diagnose the operation that failed before attempting another charge or settlement.
Payment recovery#
| Symptom | Next action |
|---|---|
| Server-settle timeout with paymentId | Save error.detail.paymentId and verify that ID. A created/cache result is unconfirmed. |
| READY health but payment remains created | Read the actual payment. Health measures capabilities, not the success of a particular purchase. |
| No ID after an interrupted create | Retry the same terms and saved idempotency key. |
| 429 / rate limit | Honor Retry-After/backoff; do not mint new purchase keys. |
| Own key says payment not found | Check studio/environment. The shared demo’s ID is not visible under your own secret. |
| Own IAP says payoutAddress missing | Set the studio wallet using POST /v1/studio/payout. |
| Degraded chain read | Mark the read unavailable; never treat cached confirmation as a fresh grant. |
Wallet and network checks#
| Symptom | Next action |
|---|---|
| USDC visible but test payment fails | Check Base Sepolia USDC first, then testnet ETH; mainnet balances do not fund testnet. |
| Login shows 8453 | Align wallet list, signed message and server verification to 84532. |
| Fallback send changes chain | Pin chain on every send path, including older buttons. |
| Nothing to withdraw | Read the correct pool/chain and distinguish credited prizes from a completed withdrawal. |
| Wallet says insufficient funds on entry | Also check RoundNotOpenError, series readiness and the actual entry window. |
Pool and operator checks#
| Symptom | Next action |
|---|---|
| pool_not_deployed | Deploy the prepare transaction, wait for its receipt, then register the mined address. |
| ownership pending | Sign the returned proof with the bound studio admin, then re-register. |
| Smart-wallet deploy or operator signature fails | Use the supported admin/operator EOA path. |
| Series has created=false | Read the recorded create transaction and series. Do not repeatedly send a new create. |
| rounds.open refuses an own pool | Use epochs.prepareSeries → epochs.enter → operator-signed settlement. |
| Settlement times out | Read the same epoch/round before retrying. A send may already have landed. |
| Local key file unreadable in Docker | Fix ownership/access for the process user; do not make it world-readable. |
Typed SDK errors#
| Error | Interpretation |
|---|---|
| InvalidAmountError / MissingFieldError | Correct amount or required fields before sending. |
| ConfigError | Key/network/RPC/provider configuration mismatch. |
| AuthError | Invalid key, forbidden capability or wrong studio. |
| WalletConnectionError / WalletTimeoutError | Wallet interaction was cancelled or timed out. |
| InsufficientGasError / PaymentFailedError | Inspect chain funds or transaction failure. |
| RoundNotOpenError / AlreadyEnteredError | Admission state rejected the attempt; inspect the exact round identity. |
| NothingToWithdrawError | No credited balance on the relevant withdrawal path. |
| ApiError | Inspect error.code and error.detail?.status / error.detail?.code. The SDK does not expose raw service nextAction or requestId fields. |
Settlement recovery#
Legacy rounds can return settling after submission. Read the same round instead of making a blind second settle request. Raw HTTP responses may contain recovery hints, but the SDK ApiError exposes HTTP status and service code in detail. Keep the round/payment ID in your own purchase record and reconcile status before retrying. For own pools, preserve the operator-signed payload and reconcile the epoch’s chain state before any resend.
Use the playground’s connection check to see current service capabilities. Do not send keys, private wallet material or full unredacted logs in a support report.
If it did not work#
Keep pending and unknown distinct from authoritative failure. Escalate with IDs and sanitized errors, never secrets.
Try one variation Compare a pending response with an authoritative failed receipt. Explain why only one permits a genuinely new purchase.
Continue with the next guide →