Response Format

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

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

All error responses across the API use a consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error"
  }
}

Error Codes

HTTP Status	Code	Description
400	BAD_REQUEST	Invalid request parameters or body
401	UNAUTHORIZED	Missing or invalid authentication
403	FORBIDDEN	Valid credentials but access denied (e.g. network policy)
404	NOT_FOUND	Resource does not exist
409	CONFLICT	Conflicting state (e.g. deactivating last API key)
429	RATE_LIMIT_EXCEEDED	Rate limit exceeded
500	INTERNAL_ERROR	Unexpected server error

See Error Handling for detailed guidance.

HTTP Status Codes

Status	Meaning
200 OK	Successful request
201 Created	Resource created (e.g. new API key or secret)
400 Bad Request	Validation error
401 Unauthorized	Authentication failure
403 Forbidden	Authorization failure
404 Not Found	Resource not found
409 Conflict	State conflict
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error

Common Headers

Request Headers

Header	Required	Description
X-API-Key	Conditional	API key authentication
Authorization	Conditional	Bearer token authentication (Bearer <token>)
Content-Type	For POST	Must be application/json for JSON request bodies
X-Language	No	Locale code for localized responses

Response Headers

Header	Description
Content-Type	Always application/json
X-Request-Id	Unique request identifier for debugging
X-RateLimit-Limit	Your rate limit ceiling
X-RateLimit-Remaining	Remaining requests in the current window
X-RateLimit-Reset	Timestamp when the rate limit window resets