Error Handling

This guide explains how to handle errors when using the API.

Error Response Format

All error responses follow a consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Additional error context
    },
    "requestId": "req_1234567890"
  }
}

HTTP Status Codes

The API uses standard HTTP status codes:

Common Error Codes

Authentication Errors

UNAUTHORIZED (401)

Invalid or missing API key.

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "requestId": "req_1234567890"
  }
}

Solution: Verify your API key is correct and included in the Authorization header.

FORBIDDEN (403)

API key doesn't have permission for the requested operation.

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have permission for this operation",
    "requestId": "req_1234567890"
  }
}

Solution: Check your API key permissions in the dashboard.

Request Errors

INVALID_REQUEST (400)

Invalid request parameters.

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid race type. Must be one of: horses, greys, harness",
    "details": {
      "field": "raceType",
      "value": "invalid"
    },
    "requestId": "req_1234567890"
  }
}

Solution: Review the API documentation and fix the request parameters.

SESSION_NOT_FOUND (404)

Session ID doesn't exist or has expired.

{
  "success": false,
  "error": {
    "code": "SESSION_NOT_FOUND",
    "message": "Session not found or has expired",
    "details": {
      "sessionId": "sess_1234567890"
    },
    "requestId": "req_1234567890"
  }
}

Solution: Create a new session and use the new session ID.

SESSION_EXPIRED (400)

Session has expired.

{
  "success": false,
  "error": {
    "code": "SESSION_EXPIRED",
    "message": "Session has expired. Please create a new session",
    "details": {
      "sessionId": "sess_1234567890",
      "expiredAt": "2024-01-15T11:30:00Z"
    },
    "requestId": "req_1234567890"
  }
}

Solution: Create a new session.

Betting Errors

PRICE_NOT_AVAILABLE (400)

Target price is not available in the market.

{
  "success": false,
  "error": {
    "code": "PRICE_NOT_AVAILABLE",
    "message": "Target price not available. Current price: 3.20",
    "details": {
      "targetPrice": 3.50,
      "currentPrice": 3.20
    },
    "requestId": "req_1234567890"
  }
}

Solution: Adjust your target price or wait for market movement.

INSUFFICIENT_FUNDS (400)

Account balance is too low.

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Insufficient funds. Required: 10.00, Available: 5.50",
    "details": {
      "required": 10.00,
      "available": 5.50
    },
    "requestId": "req_1234567890"
  }
}

Solution: Deposit funds to your account.

RUNNER_SCRATCHED (400)

Selected runner has been removed from the race.

{
  "success": false,
  "error": {
    "code": "RUNNER_SCRATCHED",
    "message": "Runner has been scratched from the race",
    "details": {
      "runnerName": "Thunder Strike"
    },
    "requestId": "req_1234567890"
  }
}

Solution: Select a different runner.

RACE_CLOSED (400)

Betting is closed for this race.

{
  "success": false,
  "error": {
    "code": "RACE_CLOSED",
    "message": "Betting is closed for this race",
    "details": {
      "raceName": "Flemington Race 1",
      "closedAt": "2024-01-15T10:00:00Z"
    },
    "requestId": "req_1234567890"
  }
}

Solution: This race is no longer accepting bets.

Server Errors

INTERNAL_SERVER_ERROR (500)

An unexpected server error occurred.

{
  "success": false,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An internal error occurred. Please try again later",
    "requestId": "req_1234567890"
  }
}

Solution: Retry the request. If the error persists, contact support with the requestId.

Error Handling Best Practices

1. Always Check Response Status

import requests

response = requests.post(url, headers=headers, json=payload)
data = response.json()

if not data.get('success'):
    # Handle error
    print(f"Error: {data.get('error', {}).get('message', 'Unknown error')}")
    raise Exception(data.get('error', {}).get('message', 'Unknown error'))

2. Handle Specific Error Codes

error_code = data.get('error', {}).get('code')
if error_code == 'SESSION_EXPIRED':
    # Create a new session
    new_session = create_session()
    # Retry the request with new session
elif error_code == 'PRICE_NOT_AVAILABLE':
    # Adjust target price or skip this bet
    print('Price not available, skipping...')
else:
    # Handle other errors
    raise Exception(data.get('error', {}).get('message', 'Unknown error'))

3. Implement Retry Logic

import time

def retry_request(func, max_retries=3):
    for i in range(max_retries):
        try:
            return func()
        except Exception as e:
            if i == max_retries - 1:
                raise
            # Wait before retrying
            time.sleep(1 * (i + 1))

4. Log Request IDs

Always log the requestId from error responses. This helps with debugging and support requests.

request_id = data.get('error', {}).get('requestId')
print(f'Request ID: {request_id}')

Next Steps

• Sessions - Understand session management and expiration