Find the failing step.
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 code, detail, nextAction, requestId and any returned receipt ID. |
Settlement recovery#
Legacy rounds can return settling after submission. Read the same round instead of making a blind second settle request. Service error hints such as wait_then_check, retry_same_key and fix_payload distinguish ambiguous sends from invalid inputs. 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.
Keep buildingYour first payment