iGaming Finder

Error Response Format

All errors follow a consistent JSON structure:

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

Every error carries this envelope — success is always false, message is human-readable, errors holds machine context (an error code plus per-endpoint details where applicable), and doc_url points to relevant documentation (null when none applies).

HTTP Status Codes

Status Meaning When
200 Success Request completed
201 Created Resource created
202 Accepted Async operation started (exports)
400 Bad Request Invalid parameters (e.g. malformed enriched_after)
401 Unauthorized Missing or invalid API key
404 Not Found Domain or resource doesn't exist
402 Payment Required Feature needs a higher plan (e.g. exports on Free)
422 Unprocessable Entity Validation failed
429 Too Many Requests Credit balance exhausted
500 Internal Server Error Unexpected server error

Authentication Errors (401)

json 
{
  "success": false,
  "message": "Unauthorized",
  "errors": {},
  "doc_url": "https://igamingfinder.com/docs/authentication.md",
  "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). The machine context lives in errors.code / errors.details:

json 
{
  "success": false,
  "message": "This feature requires the Starter plan or higher",
  "errors": {
    "code": "plan_upgrade_required",
    "details": {
      "feature": "exports",
      "current_plan": "free",
      "required_plan": "starter"
    }
  },
  "doc_url": "https://igamingfinder.com/pricing",
  "timestamp": "2026-05-03T10:30:00Z"
}
$ 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). Machine context lives in errors.code / errors.details:

json 
{
  "success": false,
  "message": "Credit balance exhausted — top up or upgrade your plan",
  "errors": {
    "code": "quota_exceeded",
    "details": {
      "granted": 2500,
      "used": 2500,
      "reserved": 0
    }
  },
  "doc_url": "https://igamingfinder.com/docs/errors.md",
  "timestamp": "2026-05-03T10:30:00Z"
}
$ 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:

python 
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:

json 
{
  "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:

json 
{
  "success": false,
  "message": "Unauthorized",
  "doc_url": "https://igamingfinder.com/docs/authentication.md"
}
Error doc_url
401 Unauthorized /docs/authentication.md
400 Bad Request /docs/errors.md
429 Too Many Requests /docs/errors.md