Response Format & Error Handling

All API responses are JSON (Content-Type: application/json). This page describes the conventions used across different endpoint groups and how errors are communicated.

Data Endpoints

Trends, references, betting, and games endpoints return data directly - no envelope wrapper:

curl -X POST https://api.odditt.com/v1/trends/mixed-flows \
 -H "X-API-Key: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"sport_id": 1, "league_id": 7, "page": 1, "page_size": 10}'

{
  "flows": [ ... ],
  "total_count": 42,
  "page": 1,
  "page_size": 10
}

Account Endpoints

Account management endpoints (/v1/account/*) wrap responses with a success field:

{
  "success": true,
  "api_keys": [ ... ]
}

Error Responses

The API uses standard HTTP status codes to indicate the success or failure of requests. All error responses return a JSON object with an error field:

{
  "error": "description of what went wrong"
}

Some endpoints return the response envelope with a success flag:

{
  "success": false,
  "error": "description of what went wrong"
}

HTTP Status Codes

Common Error Scenarios

401 - Authentication Errors

{"error": "missing bearer token"}
{"error": "invalid authorization header"}
{"error": "invalid token"}
{"error": "invalid or missing API key"}

Resolution: Check your API key or access token. If using a JWT, it may have expired - refresh your token.

400 - Validation Errors

{"error": "invalid request body"}

Resolution: Check the API Reference for required parameters and valid values.

429 - Rate Limit Errors

{"error": "rate limit exceeded"}

Resolution: See Rate Limiting for backoff strategies.

403 - Forbidden

{"error": "forbidden"}

Resolution: Your client may not have permission to access this endpoint, or your IP/domain is not in the allowlist. Contact the Odditt team.

Common Headers

Request Headers

Response Headers