v4.0

Status and Error Codes

This section shows all Gameball common error codes and how to resolve them.

HTTP Status Codes

Gameball uses HTTP response status codes to indicate the success or failure of your API requests. If your request fails, Gameball returns an error using the appropriate status code.

  • 2XX codes indicate success and that the request worked as intended

  • 4XX codes indicate errors due to some mistakes in the request.

  • 5XX codes indicate an error with Gameball's servers.

Error Object

The error response is returned whenever a request fails (returns non-2XX Http status code) due to issues such as authentication problems, incorrect payloads, or server-side errors. It provides essential details to help the user understand what went wrong and how to correct it.

Error Response Attributes:

  • code: The specific internal Gameball error code identifying the issue.

  • type: A broad category for the error (e.g., "Authentication Error," "Payload Error," "Server Error").

  • message: A clear explanation of what caused the error.

  • documentationUrl: A URL linking to relevant Gameball documentation for further details on the request and error resolution.

  • requestId: A unique identifier for the request, helpful for tracking and debugging.

Example Error Response:

{
    "code": 3000,         
    "type": "Payload Error",     
    "message": "An error occurred while processing your request. Please try again later.", 
    "documentationUrl": "https://developer.gameball.co/4.0/rest-api/api-reference", 
    "requestId": "12345abcde" 
}

Possible Error Categories

  • AUTHENTICATION_ERROR (1XXX) These errors occur when the request lacks proper authentication or authorization. It could be due to missing or invalid credentials, such as a missing API key or incorrect token.

  • REQUEST_ERROR (2XXX) Request errors are caused by issues with the format or content of the request. This could include missing required parameters, incorrect URL formatting, or invalid query parameters.

  • PAYLOAD_ERROR (3XXX) Payload errors refer to issues in the request body (payload), such as missing data, invalid values, or unsupported content types. These errors can occur when data required to process the request is incorrect or incomplete.

  • GENERAL_ERROR (4XXX) General errors are non-specific errors that could apply to various scenarios where something goes wrong in the request processing, but no detailed cause is provided.

  • SERVER_ERROR (5XXX) Server errors occur when there is an issue with the server processing the request. These could be due to internal server issues, timeouts, or unavailable services.

  • CONFIGURATIONS_ERROR (6XXX) Configuration errors are triggered when there are issues with the settings or configurations of the Gameball system. These could occur if a feature is disabled or not properly configured.

  • CUSTOMER_ERROR (7XXX) Customer errors happen when there is an issue with the customer’s data. For example, if the customer ID is not found, or the customer data is invalid.

  • SUBSCRIPTION_ERROR (8XXX) Subscription errors occur when a feature is attempted but the customer’s subscription plan does not support it or it’s not enabled for their account.

  • TRANSACTIONS_ERROR (9XXX) Transaction errors relate to issues during financial transactions in Gameball, such as invalid transaction data, insufficient balance, or issues with reversing or holding transactions.

Error Codes

Gameball sends an error code in the body of the response, each code has a corresponding error message that is descriptive of what went wrong, below are the codes along with their description.

1000: Unauthorized (401 Unauthorized)

  • Description: Unauthorized access. The client must authenticate to access the resource.

  • Example: Trying to access a protected API without providing valid credentials.

1001: Secret Key Required (401 Unauthorized)

  • Description: A valid secret key is required for this operation.

  • Example: Attempting to access an API without including the required secretKey.

1002: Forbidden (403 Forbidden)

  • Description: You do not have permission to access this resource.

  • Example: Trying to perform an action that requires higher-level permissions than the client possesses.

2000: Precondition Failed (412 Precondition Failed)

  • Description: A required condition for this request was not met.

  • Example: Submitting an order that does not meet the required conditions, such as failing to provide a required field like customerId.

3000: Missing Arguments (400 Bad Request)

  • Description: Required arguments are missing in the request.

  • Example: Trying to submit an order without including the required customerId or transactionId fields.

3001: Null Arguments (422 Unprocessable Entity)

  • Description: Null values are passed for required arguments.

  • Example: Sending a request with a null value for required fields like points or amount in a rewards transaction.

3002: Not Supported Extension (415 Unsupported Media Type)

  • Description: The provided file extension is not supported.

  • Example: Uploading a file with an unsupported extension like .txt where only .csv or .json is allowed.

3003: Invalid Value (422 Unprocessable Entity)

  • Description: The provided value is invalid or does not meet expected criteria.

  • Example: Sending a request with an invalid transactionId format.

3004: Not Achieved (400 Bad Request)

  • Description: The operation was not achieved as expected.

  • Example: Attempting to apply a reward campaign that is not eligible for the customer.

3005: Body Hashed Invalid (422 Unprocessable Entity)

  • Description: The hashed value in the request body is invalid or incorrect.

  • Example: Trying to submit a request where the bodyHashed value doesn't match the expected value due to tampering or an error in hashing.

3006: Name Length Invalid (422 Unprocessable Entity)

  • Description: The name provided is too short or too long based on system restrictions.

  • Example: Attempting to create or update a rule with a name that exceeds the character limit.

3007: Name Already Exists (409 Conflict)

  • Description: The provided name already exists in the system.

  • Example: Trying to create a new player or campaign with a name that is already used.

3008: Email Already Exists (409 Conflict)

  • Description: The provided email already exists in the system.

  • Example: Attempting to register a new customer with an email that is already in use.

3009: Inactive (422 Unprocessable Entity)

  • Description: The entity in the request is inactive and cannot be used.

  • Example: Trying to reward a customer who has been marked as inactive in the system.

3010: Invalid Leveling Method (422 Unprocessable Entity)

  • Description: The leveling method provided is invalid.

  • Example: Trying to update a customer's tier using an invalid leveling method.

3011: Limit Exceed (422 Unprocessable Entity)

  • Description: The operation exceeds the allowed limits.

  • Example: Attempting to reward more points than the maximum allowed limit for a customer.

3012: Recaptcha Invalid (422 Unprocessable Entity)

  • Description: The reCAPTCHA validation failed.

  • Example: Submitting a form that requires CAPTCHA validation, but the CAPTCHA was either incorrect or failed to validate.

3013: Not Supported (415 Unsupported Media Type)

  • Description: The file or request type is not supported by the system.

  • Example: Uploading a file with a type that is not accepted by the API, such as a non-JSON payload where JSON is expected.

3014: Read Only (423 Locked)

  • Description: The resource is read-only and cannot be modified.

  • Example: Trying to update a player's score when the score is set as a read-only field.

3015: Edit Required (423 Locked)

  • Description: The resource requires editing before it can be used.

  • Example: Trying to apply a coupon that has expired and needs to be updated before further use.

3016: Invalid Payload (400 Bad Request)

  • Description: The payload provided in the request is invalid.

  • Example: Submitting a request with a malformed JSON body or missing critical fields.

3017: Event Not Found (404 Not Found)

  • Description: The requested event could not be found in the system.

  • Example: Trying to fetch details for an event that doesn't exist or has been deleted.

4000: Failed (400 Bad Request)

  • Description: The operation failed due to an internal issue.

  • Example: Sending a transaction that violates the business rules, such as trying to redeem an expired coupon.

4004: Not Found (404 Not Found)

  • Description: The requested resource could not be found.

  • Example: Trying to retrieve a transaction that does not exist or using an incorrect transactionId.

4500: Something Wrong (400 Bad Request)

  • Description: There was a general error in processing the request.

  • Example: Submitting a transaction where an unexpected error occurs during processing.

5000: Internal Server Error (500 Internal Server Error)

  • Description: An unexpected error occurred on the server.

  • Example: Trying to process a transaction when the server is temporarily down.

5003: Service Unavailable (503 Service Unavailable)

  • Description: The service is temporarily unavailable.

  • Example: Attempting to access an API during a maintenance window or when the service is down for other reasons.

6000: Gameball Disabled (422 Unprocessable Entity)

  • Description: The Gameball service is disabled for the client and needs to be enabled first.

  • Example: Trying to submit a reward transaction when Gameball is disabled for the client account.

6001: Cashback Disabled (422 Unprocessable Entity)

  • Description: Cashback points are disabled and cannot be used.

  • Example: Trying to apply cashback rewards when the cashback service is disabled for the client.

6002: Default Language Not Set (422 Unprocessable Entity)

  • Description: The client's default language has not been set in the system.

  • Example: Trying to send a notification without a language preference when the default language has not been configured.

6003: Cannot Access Coupon Configurations (403 Forbidden)

  • Description: The client does not have access to coupon configurations.

  • Example: Trying to modify coupon configurations without the necessary permissions.

7000: Customer Not Found (404 Not Found)

  • Description: The customer with the provided external ID could not be found.

  • Example: Trying to fetch customer details using an invalid customerId.

7001: Customer Already Exists (409 Conflict)

  • Description: A customer with this external ID already exists in the system.

  • Example: Trying to create a new customer with an external ID that is already in use.

7002: Customer Already Referred (409 Conflict)

  • Description: This customer has already been referred.

  • Example: Attempting to process a referral for a customer who has already been referred by another user.

7003: Referral Code Not Found (404 Not Found)

  • Description: The referral code provided does not exist.

  • Example: Trying to redeem a referral using an invalid or expired referral code.

7004: Guest Identifier Already Exists (409 Conflict)

  • Description: A guest with this identifier already exists in the system.

  • Example: Trying to create a new guest account using an identifier that already exists.

7005: Customer Already Referred (409 Conflict)

  • Description: This customer has already been referred.

  • Example: Trying to refer a customer who has already been referred.

7006: Invalid Referral (422 Unprocessable Entity)

  • Description: The referral provided is invalid or cannot be processed.

  • Example: Attempting to process a referral using invalid referral details.

8000: Feature Unavailable (403 Forbidden)

  • Description: The service or feature you're trying to access is temporarily unavailable.

  • Example: Attempting to use a premium feature when the subscription has expired or is temporarily unavailable.

9000: Transaction Type Non-Reversible (422 Unprocessable Entity)

  • Description: This transaction type cannot be reversed.

  • Example: Trying to reverse a transaction type that does not support reversal, such as certain cashback transactions.

9001: Transaction Already Cancelled (409 Conflict)

  • Description: The transaction has already been cancelled.

  • Example: Trying to cancel a transaction that has already been processed and cancelled.

9002: Transaction Not Found (404 Not Found)

  • Description: The specified transaction could not be found in the system.

  • Example: Trying to retrieve a transaction using an invalid transactionId.

9003: Transaction Time Already Exists (409 Conflict)

  • Description: A transaction with this timestamp already exists.

  • Example: Trying to process a transaction at a specific time when a transaction with the same timestamp is already recorded in the system.

9004: Transaction ID Already Exists (409 Conflict)

  • Description: A transaction with this ID already exists in the system.

  • Example: Trying to submit a transaction with a transactionId that has already been used.

9005: Reversed Transaction Not Found (404 Not Found)

  • Description: The reversed transaction ID could not be found on the client system.

  • Example: Attempting to reverse a transaction using an invalid or non-existent transaction ID.

9006: Transaction Hold Reference Not Found (404 Not Found)

  • Description: The hold reference for this transaction could not be found.

  • Example: Trying to release or reverse a transaction hold using an invalid or non-existent reference.

9007: Transaction Time Not Valid (422 Unprocessable Entity)

  • Description: The provided transaction time is invalid.

  • Example: Submitting a transaction with a timestamp that is either in the future or formatted incorrectly.

9008: Insufficient Balance Points (422 Unprocessable Entity)

  • Description: There are insufficient balance points available for the transaction.

  • Example: Trying to redeem more points than the customer has available in their balance.

PreviousRate LimitingNextCustomers

Last updated