Error Response Format

All errors follow a consistent JSON structure:

{
  "success": false,
  "message": "Human-readable error description",
  "errors": {},
  "timestamp": "2026-05-03T10:30:00Z"
}

HTTP Status Codes

Authentication Errors (401)

{
  "success": false,
  "message": "Unauthorized",
  "errors": {},
  "timestamp": "2026-05-03T10:30:00Z"
}

Check that your API key is valid and passed via X-API-Key or Authorization: Bearer header.

Plan Upgrade Required (402)

Returned when your plan doesn't include the requested feature (e.g. exports require Starter or higher). Uses the same error.code / error.details structure as quota errors:

{
  "error": {
    "code": "plan_upgrade_required",
    "message": "This feature requires the Starter plan or higher",
    "details": {
      "feature": "exports",
      "current_plan": "free",
      "required_plan": "starter"
    }
  },
  "doc_url": "https://igamingfinder.com/pricing"
}

$ help --topic=tip

◆ See pricing for what each plan includes. 402 is distinct from 429: a 402 means your plan doesn't include the feature (upgrade), a 429 means you're out of credits (top up or wait for renewal).

Quota Exceeded (429)

Returned when your credit balance is exhausted (credits are granted upfront and never expire — see pricing). Note: quota errors use a different structure with error.code and error.details for programmatic handling:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Credit balance exhausted — top up or upgrade your plan",
    "details": {
      "granted": 2500,
      "used": 2500,
      "reserved": 0,
      "quota": 2500
    }
  },
  "doc_url": "https://igamingfinder.com/docs/errors.md"
}

$ help --topic=tip

◆ Check your remaining credits with GET /api/v1/igaming/account before starting enrichment batches.

$ help --topic=warning

⚠ Deprecated: details.quota is an alias of details.granted and will be removed in a future release — migrate to granted.

Handling Errors

Retry Strategy

For 429 responses, wait until your quota resets at the start of the next billing period, or upgrade your plan.

For 500 responses, retry with exponential backoff:

import time
import requests

def api_call_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        r = requests.get(url, headers=headers)
        if r.status_code == 500:
            time.sleep(2 ** attempt)
            continue
        return r
    raise Exception(f"Failed after {max_retries} retries")

Validation Errors (422)

Field-level errors include the field name and description:

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "domain": ["can't be blank"]
  },
  "timestamp": "2026-05-03T10:30:00Z"
}

Self-Correction for AI Agents

Error responses include a doc_url field linking to relevant documentation:

{
  "success": false,
  "message": "Unauthorized",
  "doc_url": "https://igamingfinder.com/docs/authentication.md"
}