Diagnose integration failures

Separate HTTP transport status from wallet data.statusCode. HTTP 200 alone is not a successful wallet operation: data.statusCode must equal 1000. Verify the response signature and echoed request ID before trusting either response data or an error message. Unsigned authentication errors may occur; their bodies are untrusted.

Common errors

Symptom	Likely cause	Resolution
HTTP 401	Wrong environment secret/slug; missing header; old body-only HMAC.	Check the canonical signature and environment settings.
Signature matches locally but fails remotely	JSON changed after signing; wrong path; proxy/body parser reserialization; hex case/length.	Sign and send one exact buffer; verify raw bytes; use lowercase 64-character hex.
Requests work intermittently with 401	Clock drift or noncanonical timestamp.	Synchronize UTC; generate a fresh new Date().toISOString() for each attempt.
Callback fails only behind a URL prefix	Signature includes the callback base prefix.	Sign the logical /transactions/* path as explained in onboarding.
/freebets/create fails authentication	Obsolete path, blocked by the current signing guard.	Use /freeplays/create with required externalReference, future expiry and count up to 10,000.
HTTP 400 VALIDATION_FAILED	Missing or wrong field type; invalid UUID or amount precision.	Compare the request to its endpoint schema. Amounts are strings, counts are JSON integers.
Signed launch 503 PROVIDER_UNAVAILABLE	Downstream launch failure or unavailable game/currency configuration.	Confirm enabled settings and connectivity with Moonshot; next attempt uses a fresh key/session.
HTTP 409 CONFLICT	Reused transaction/grant key with changed payload, original bet mismatch, or invalid state.	Compare the original operation; never generate a new transaction ID to bypass an unknown wallet result.
Freeplay 404 NOT_FOUND	No grant for this operator and original key/id.	Trust absence only after verifying the signed response; confirm environment and key.
HTTP 200 with 5100	Insufficient or invalid balance.	Do not accept the bet; verify the player's wallet balance.
HTTP 200 with 5000	Business-level server error.	It is not an HTTP 5xx retry signal. Reconcile the recorded operation and agreed recovery flow.
Verified 409 TREASURY_LIMIT_EXCEEDED	Operator treasury/exposure rejection.	No debit; resolve the agreed exposure limit. The provider maps this particular verified rejection to 5200.
Duplicate callback rejected with 3000	Receiver returns a new duplicate error instead of the original result.	Replay stored response data and original operator transaction ID, with a fresh response signature for this attempt.
Win of 0 rejected	Receiver assumes every settlement must be positive.	Close the accepted bet without credit; zero-payout/freeplay loss is valid.
Double debit or credit	Nonatomic idempotency check, missing wallet lock, or memory-only deduplication.	Store ledger, domain transition and wallet mutation in one durable transaction with uniqueness and locking.
Late win/cancel rejected after logout	Only the active login session is checked.	Resolve player/game/currency/session ownership from the original accepted bet.
Response signature fails	Missing request echo, wrong HTTP status in signature, changed response bytes, HTML/redirect from proxy.	Sign the exact bytes after serialization; bypass no verification checks; fix upstream routing.
HTTP 301/302/307/308	Callback path or HTTPS normalization redirect.	Register the final URL and expose exact routes directly; clients reject redirects.
Timeout	Backend exceeds the configured timeout, networking failure, or response lost after commit.	Inspect durable ledger before retry/reconciliation. A timeout does not mean no mutation occurred.

Game does not load

1. Confirm the backend received and verified a successful launch and your frontend used the complete returned URL. Generate a fresh launch for a new attempt.
2. Check iframe dimensions and its parent's height in the browser layout tools.
3. Inspect browser errors for CSP frame-src, game frame-ancestors, X-Frame-Options, mixed content, blocked scripts or failed WebSocket connections.
4. Confirm the embedding origin and game origin configuration with Moonshot. Test normal browser settings on desktop and mobile.
5. If callbacks fail when play starts, confirm Moonshot can reach your registered public HTTPS wallet. localhost and 127.0.0.1 are only for local simulation.

See the iframe example for the complete frontend handoff.

Support report

Send [email protected] the environment, operator slug, endpoint, UTC time, request UUID, transaction/bet or grant reference, HTTP status, verified business/error code and whether the ledger committed. Include reproduction steps and redacted browser/HTTP errors. For a launch issue, include the launch idempotency key and enabled game/currency.

Do not include HMAC secrets, signatures, launch URLs/tokens, personal player context or complete raw payloads. Keep raw-byte comparison inside your secured debugging environment. Agree a secure channel if additional diagnostics are required.