Error Codes & Rate Limits

Error Response Format

All API errors return a JSON object with an error field:

{
  "error": "Human-readable error message"
}

Some endpoints include additional context fields.

HTTP Status Codes

Status	Meaning	When
200	Success	GET requests, updates
201	Created	POST creating new resources
202	Accepted	Event ingestion (async processing)
204	No Content	DELETE operations
400	Bad Request	Missing/invalid fields, validation errors
401	Unauthorized	Missing or invalid API key / JWT
403	Forbidden	Insufficient permissions, account locked
404	Not Found	Resource doesn’t exist
409	Conflict	Version conflict (cloud saves)
413	Payload Too Large	Batch too large, save data too big
429	Too Many Requests	Rate limit or quota exceeded
500	Internal Server Error	Unexpected server error

Rate Limiting

All API endpoints are rate-limited to 1,000 requests per minute per API key (or per IP for unauthenticated routes).

When rate-limited, the response is:

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded, retry in 60 seconds"
}

Headers included:

Header	Description
X-RateLimit-Limit	Max requests per window
X-RateLimit-Remaining	Requests left in current window
X-RateLimit-Reset	Seconds until window resets
Retry-After	Seconds to wait (on 429)

Event Quota

Each game has a monthly event quota based on the billing tier:

Tier	Monthly Events
Free	100,000
Indie	1,000,000
Studio	10,000,000

When the quota is exceeded, POST /v1/track returns:

{
  "error": "Monthly event quota exceeded",
  "quota": {
    "current": 100001,
    "limit": 100000,
    "remaining": 0
  }
}

Common Error Scenarios

Missing API Key

curl https://api.questdata.io/v1/config
# 401: { "error": "Missing x-game-api-key header" }

Invalid API Key

curl https://api.questdata.io/v1/config -H "x-game-api-key: wrong-key"
# 401: { "error": "Invalid API key" }

Expired JWT

curl https://api.questdata.io/v1/games -H "Authorization: Bearer expired-token"
# 401: { "error": "Token expired" }

Validation Error

curl -X POST https://api.questdata.io/v1/track \
  -H "x-game-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
# 400: { "error": "event_name is required" }