Error Codes

Complete reference of all error codes returned by the Slotty Labs API.

Operator-Facing Errors (80xxx)

These errors are returned to operator backends when making API calls.

Code	HTTP Status	Description
80001	401	Invalid API Key — The API key is missing, malformed, or revoked
80002	401	Invalid Signature — HMAC signature verification failed
80003	429	Rate Limited — Too many requests; check Retry-After header
80004	400	Invalid Request — Request body validation failed
80005	403	Forbidden — API key does not have permission for this action
80006	404	Resource Not Found — The requested resource does not exist
80007	409	Conflict — Resource already exists or state conflict
80008	402	Insufficient Balance — Player does not have enough balance
80009	503	Service Unavailable — Platform is temporarily unavailable
80010	404	Player Not Found — No player found with the given ID
80011	400	Invalid Currency — Currency code is not supported

Example Error Response

{
  "success": false,
  "error": {
    "code": "80001",
    "message": "Invalid API key",
    "details": {
      "hint": "Ensure you are using the correct environment key (sandbox vs production)"
    }
  },
  "requestId": "req_abc123"
}

Game Engine Errors

These errors occur during game play, typically returned via WebSocket.

Code	Description
30007	Insufficient Balance — Player cannot afford the bet amount
30601	Round Not Found — No active round for this player/game
30602	Invalid Action — The action is not valid for the current game state
30603	Round Already Complete — Attempting to act on a finished round
30021	Game Not Available — Game is disabled or under maintenance

Example WebSocket Error

{
  "type": "error",
  "payload": {
    "code": "30007",
    "message": "Insufficient balance",
    "details": {
      "required": 20.00,
      "available": 15.50,
      "currency": "USD"
    }
  },
  "requestId": "req-001",
  "timestamp": 1719849600000
}

SSO Errors

These errors are specific to the SSO authentication flow.

Code	HTTP Status	Description
SSO_INVALID_SIGNATURE	401	HMAC signature on the SSO token creation request is invalid. Check your webhook secret and signing algorithm.
SSO_TOKEN_ALREADY_USED	409	The SSO launch token has already been exchanged for a session. Tokens are single-use; create a new one.

SSO_INVALID_SIGNATURE

{
  "success": false,
  "error": {
    "code": "SSO_INVALID_SIGNATURE",
    "message": "HMAC signature verification failed",
    "details": {
      "hint": "Verify the signing payload format: timestamp.METHOD.path.body"
    }
  },
  "requestId": "req_xyz789"
}

SSO_TOKEN_ALREADY_USED

{
  "success": false,
  "error": {
    "code": "SSO_TOKEN_ALREADY_USED",
    "message": "This SSO token has already been exchanged",
    "details": {
      "jti": "tok_abc123",
      "exchangedAt": "2026-01-15T10:30:00.000Z"
    }
  },
  "requestId": "req_def456"
}

Error Handling Best Practices

Retry Logic

Error Code	Retryable	Strategy
80003 (Rate Limited)	✅	Wait for Retry-After header value
80009 (Service Unavailable)	✅	Exponential backoff (1s, 2s, 4s, 8s, max 30s)
30007 (Insufficient Balance)	❌	Prompt player to deposit
80001 (Invalid API Key)	❌	Check configuration
80002 (Invalid Signature)	❌	Check signing implementation
All other codes	❌	Log and investigate

SDK Error Handling

import { SlottyClient, SlottyApiError } from '@slottylabs/sdk';

const client = new SlottyClient({ apiKey: 'sk_sandbox_...' });

try {
  await client.auth.createSSOToken({ ... });
} catch (err) {
  if (err instanceof SlottyApiError) {
    // Structured API error
    console.error(`Error ${err.code}: ${err.message}`);
    console.error(`Request ID: ${err.requestId}`);

    if (err.code === '80003') {
      // Rate limited — retry after delay
      const retryAfter = err.body?.retryAfter ?? 60;
      await sleep(retryAfter * 1000);
      // Retry the request...
    }
  } else {
    // Network error, timeout, etc.
    console.error('Network error:', err.message);
  }
}

HTTP Status Code Summary

Status	Meaning	Common Causes
200	Success	Request processed successfully
201	Created	Resource created (e.g., player, webhook)
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Invalid or missing API key / signature
402	Payment Required	Insufficient balance
403	Forbidden	Insufficient permissions
404	Not Found	Resource does not exist
409	Conflict	Duplicate resource or state conflict
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error (contact support)
503	Service Unavailable	Temporary maintenance or overload