> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playstarters.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Resolve common issues with the Operator API, the Seamless Wallet callback, and going live.

Work through the relevant section for your issue type. If the problem persists, [contact support](/support/contact) with your operator ID, the `requestId`, timestamps, and request/response payloads.

## Operator API errors

| HTTP Status | Likely cause                                                      | Resolution                                                                                                                              |
| ----------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `401`       | Missing or malformed `Authorization` header.                      | Verify the header format is exactly `Authorization: ApiKey ps_<your_api_key>`. Check your HTTP client is not stripping it on redirects. |
| `403`       | API key is valid but not authorized for the resource.             | Confirm the key belongs to the correct operator account. Contact support if the issue persists.                                         |
| `404`       | Resource not found (e.g. unknown `gameId` on `/operator/launch`). | Re-fetch the catalog from `/operator/games` to confirm the ID is still enabled.                                                         |
| `400`       | Malformed JSON or missing required field.                         | Validate the request body against the endpoint schema.                                                                                  |
| `429`       | Rate limit exceeded.                                              | Back off and retry with exponential delay.                                                                                              |
| `5xx`       | Transient PlayStarters error.                                     | Retry with exponential back-off. Contact support if it persists.                                                                        |

## Authentication issues

1. **Header format.** Must be `Authorization: ApiKey ps_<your_api_key>` — not `Bearer`, not `Token`.
2. **Environment match.** Make sure you are calling the base URL that matches your key (sandbox vs production).
3. **Key rotation.** If the key may have been leaked, contact PlayStarters to rotate it. Old keys are invalidated immediately on rotation.

## Game launch issues

**`/operator/launch` returns a URL but the game does not load**

* Confirm the `gameUrl` is loaded **immediately**. Launch URLs are short-lived.
* Open the URL in an iframe with the correct `allow` attributes (autoplay, fullscreen) or in a new window.
* Check the browser console and network tab for CSP, mixed-content (HTTP vs HTTPS), or cross-origin issues on your site.

**Game opens but balance shows zero**

* PlayStarters calls your wallet endpoint with `type: "BALANCE"` immediately after the game opens. Check your endpoint logs for that request.
* Verify your endpoint returns `{ "balance": <number> }` with HTTP `200`. A non-`200` response, a malformed body, or a missing `balance` field will surface as `0` (or a generic error) in the game.
* Confirm the `currency` you passed to `/operator/launch` matches the currency of the balance your endpoint returns.

## Seamless Wallet callback issues

**Player charged twice for the same spin**

* Your endpoint is not idempotent. Implement deduplication on `requestId` — see [Idempotency](/api/wallet/idempotency).

**`WIN` or `VOID` arrives for an unknown `parentTransactionId`**

* Don't fail the request. Log it for investigation and respond `200 OK` with the player's current balance. Failing the request causes retries and reconciliation drift.

**Spins blocked when the player has funds**

* Check whether your endpoint is returning `400 { "msg": "Insufficient user credit" }` only for genuinely insufficient balances. Returning `400` for transient errors (DB timeouts, etc.) will incorrectly block the game.

## Going-live checklist

<Note>
  Before switching from sandbox to production:

  * ✅ Production **Operator API key** stored as an environment variable.
  * ✅ Production **API key** stored as an environment variable; your wallet endpoint validates the `Authorization: Bearer` header (PlayStarters sends your same API key as a Bearer token).
  * ✅ Base URL switched from sandbox to production for all Operator API calls.
  * ✅ Wallet endpoint reachable from PlayStarters with valid TLS.
  * ✅ Idempotency on `requestId` verified with a duplicate-request test.
  * ✅ End-to-end flow tested: launch → `BALANCE` → `BET` → `WIN` → `VOID` with reconciled balances on both sides.
</Note>

<Info>
  If you've followed this guide and the issue persists, [submit a support ticket](/support/contact). Include your operator ID, the affected endpoint, the `requestId`, the timestamp (with timezone), and the request/response payloads with secrets redacted.
</Info>