Error Codes

Auto-generated from the error code registry. Last generated: 2026-03-27 Run npm run docs:errors -w @king-jewel/api to regenerate.

All KINGSTONE API errors include a machine-parseable error code in the errorCode field. Codes follow the format KS-XXXX where the number range indicates the category.

Authentication Errors (KS-40xx)

Code	HTTP Status	Message	Resolution
KS-4001	401	Missing X-API-Key header	Include the X-API-Key header with a valid API key in your request.
KS-4002	401	Invalid API key	Check that your API key is correct. Keys start with "ks_" for sandbox or "kp_" for production.
KS-4003	401	API key is revoked or inactive	Contact Predigy to issue a new API key.
KS-4004	401	API key has expired	Contact Predigy to renew your API key.
KS-4005	401	Partner account is deactivated	Contact Predigy to reactivate your partner account.

Validation Errors (KS-41xx)

Code	HTTP Status	Message	Resolution
KS-4101	400	Request validation failed	Check the request body/parameters against the API documentation.
KS-4102	400	Required field missing	Include all required fields in your request body.
KS-4103	400	Wager amount out of range	Ensure wager is between the game's minimum and maximum wager limits.
KS-4104	400	Invalid PAR sheet data	Verify your PAR sheet JSON matches the required schema and RTP math is correct.
KS-4105	400	Invalid date format	Use YYYY-MM-DD format for date parameters.
KS-4106	400	Invalid webhook URL	Provide a valid HTTPS URL for webhook registration.
KS-4107	400	Invalid webhook event types	Use valid event types: spin.large_win, settlement.report_ready, block.low_reserve, api_key.expiring.
KS-4108	409	Game config name already exists	Choose a unique config name for the game.
KS-4109	400	minWagerUsd must be less than maxWagerUsd	Ensure the minimum wager is strictly less than the maximum wager.

Game/Resource Errors (KS-42xx)

Code	HTTP Status	Message	Resolution
KS-4006	403	Game not found or not registered to this partner	Verify the game ID and ensure it is registered to your partner account.
KS-4201	404	Game not found	Verify the game ID and ensure it is registered to your partner account.
KS-4202	400	Game is not active	Activate the game or contact Predigy support.
KS-4203	503	Game outcome queue exhausted	Wait for automatic block generation. If this persists, contact Predigy support.
KS-4204	404	Player not found	Verify the external player ID. Players are auto-created on first spin.
KS-4205	404	PAR sheet not found	Upload a PAR sheet first using POST /par-sheets.
KS-4206	404	Webhook not found	Verify the webhook ID and ensure it belongs to your partner account.
KS-4207	403	Webhook does not belong to this partner	Verify the webhook ID belongs to your partner account.
KS-4208	400	PAR sheet is not active	Only ACTIVE PAR sheets can be used for game registration.
KS-4209	404	Partner not found	Verify the partner ID in your request.
KS-4210	403	Partner is deactivated	Contact Predigy to reactivate this partner account.
KS-4211	409	Partner with this slug already exists	Choose a unique slug for the partner.
KS-4212	404	API key not found	Verify the API key ID in your request.
KS-4213	403	API key does not belong to this partner	Verify the API key belongs to your partner account.
KS-4214	404	No games registered for this partner	Register at least one game before generating settlement reports.
KS-4215	404	Resource not found	Verify the resource ID in your request.

Settlement Errors (KS-43xx)

Code	HTTP Status	Message	Resolution
KS-4301	404	Settlement report not found	Verify the date format (YYYY-MM-DD). Reports are generated daily.
KS-4302	409	Settlement report already acknowledged	This report has already been acknowledged and cannot be changed.
KS-4303	409	Settlement report already disputed	This report has already been disputed.
KS-4304	409	Settlement report status does not allow this action	Only GENERATED or PENDING reports can be acknowledged or disputed.

Rate Limit Errors (KS-429x)

Code	HTTP Status	Message	Resolution
KS-4291	429	Rate limit exceeded for spin requests	Wait and retry after the Retry-After period. Check X-RateLimit-* headers.
KS-4292	429	Rate limit exceeded for API requests	Wait and retry after the Retry-After period. Check X-RateLimit-* headers.

Server Errors (KS-50xx)

Code	HTTP Status	Message	Resolution
KS-5004	500	Authentication service error	Retry after a brief delay. If the issue persists, contact Predigy support.
KS-5001	500	Internal server error	Retry after a brief delay. If the issue persists, contact Predigy support.
KS-5002	503	Service temporarily unavailable	The service is under maintenance. Retry after a brief delay.
KS-5003	500	Spin processing failed	Retry the spin. The wager was not deducted. If this persists, contact Predigy.
KS-5005	500	Failed to register game	Retry after a brief delay. If the issue persists, contact Predigy support.
KS-5006	500	Failed to upload PAR sheet	Retry after a brief delay. If the issue persists, contact Predigy support.
KS-5007	500	Failed to create partner	Retry after a brief delay. If the issue persists, contact Predigy support.
KS-5008	500	Failed to issue API key	Retry after a brief delay. If the issue persists, contact Predigy support.
KS-5009	500	Failed to generate settlement report	Retry after a brief delay. If the issue persists, contact Predigy support.
KS-5010	500	Failed to resolve or create partner player	Retry after a brief delay. If the issue persists, contact Predigy support.

Using Error Codes in Your Application

import { KingstoneClient, KingstoneApiError } from '@kingstone/sdk';

try {
  await client.spin({ gameId: 1, playerId: 'p1', wagerUsd: 0.25 });
} catch (error) {
  if (error instanceof KingstoneApiError) {
    switch (error.errorCode) {
      case 'KS-4103':
        showUserMessage('Invalid wager amount. Please adjust your bet.');
        break;
      case 'KS-4291':
        showUserMessage('Please wait a moment before spinning again.');
        break;
      case 'KS-5001':
      case 'KS-5002':
        showUserMessage('Service temporarily unavailable. Retrying...');
        await retryWithBackoff(() => client.spin(/* ... */));
        break;
      default:
        showUserMessage(`Error: ${error.message}`);
    }
  }
}

Retryable vs. Non-Retryable

The SDK's KingstoneApiError.retryable property is true for:

• 429 errors — rate limited, safe to retry after waiting
• 5xx errors — server-side issues that may resolve on their own

All 4xx errors (except 429) are not retryable — the request itself needs to be changed.

See the Error Handling guide for retry patterns with exponential backoff.