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
    }
  },
  "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.

Handling Errors

Retry Strategy

For 429 responses, top up your credits or upgrade your plan. Credits are an upfront ledger — granted never expires and does not reset monthly.

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"
}