Error Response

Overview

This section details the standard error responses that may be returned by the OAS API. Proper error handling is essential for a robust integration between GPAS and the Operator Account System.

Error Response Format

Error responses follow a consistent JSON format:

{
  "code": 1001,
  "type": "SYSTEM_ERROR",
  "message": "System Error"
}

Standard Error Codes

The following table lists the standard error codes that should be implemented:

HTTP Status	Code	Type	Message	Description
500	1001	SYSTEM_ERROR	System error	Error or unexpected exception in the system
400	1002	INVALID_TX_ID	Invalid transaction id	The transaction id specified with the rollback request is not known by the wallet platform.
400	1003	DUPLICATE_TX_ID	Already transaction	The transaction is already registered in the wallet
400	1004	INVALID_WALLET_SESSION	Invalid wallet session	The provided user wallet session is invalid.
400	1005	INVALID_WALLET_ID	Invalid wallet id	The provided wallet id is invalid.
400	1006	SIGNATURE_FAILED	Signature failed	Request signature error
400	1007	INSUFFICIENT_FUNDS	Insufficient funds	The player’s balance in the wallet is smaller than the “amount” parameter specified by the wager request.
400	1008	USER_BLOCKED	User Blocked	User who was blocked by the operator
400	1009	INVALID_GAME_ID	Invalid game id	The provided game id is not valid
500	1010	”EXAMPLE_ERROR”	Custom Error	Error that the operator considers and is not in this list

Custom Error Types

The error code 1010 must be a TYPE created by the operator at their discretion, for example “CURRENCY_ERROR”, “LANG_ERROR”, it is an error that is not in the list but the wallet considers valid.

Example Error Response

HTTP STATUS 500

{
  "code": 1001,
  "type": "SYSTEM_ERROR",
  "message": "System Error"
}

Implementation Guidelines

When implementing error handling in the OAS API:

1. Use Appropriate HTTP Status Codes: Return the correct HTTP status code for each error type
2. Include All Required Fields: Ensure that all error responses include the code, type, and message fields
3. Be Consistent: Use the standard error codes and messages as defined in this document
4. Provide Clear Messages: Error messages should be clear and helpful for troubleshooting
5. Log Errors: Log all errors on the server side for monitoring and debugging purposes

Common Error Scenarios

Invalid Authentication

If the authentication token provided in the Authorization header during the /sessions call is invalid or expired, the OAS should return a custom error:

{
  "code": 1010,
  "type": "INVALID_AUTH_TOKEN",
  "message": "Invalid auth token"
}

This error is distinct from code 1004, which should be reserved for invalid walletSessionId during transactional operations (Debit, Credit, etc.).

Insufficient Funds

If the player doesn’t have enough balance for a debit operation:

{
  "code": 1007,
  "type": "INSUFFICIENT_FUNDS",
  "message": "Insufficient funds"
}

Duplicate Transaction

If a transaction with the same external reference already exists:

{
  "code": 1003,
  "type": "DUPLICATE_TX_ID",
  "message": "Already transaction"
}