API Documentation

Error Handling

HTTP status codes and error responses

HTTP Status Codes

Code	Meaning	Billed?
`200`	Success	Yes
`201`	Created	Yes
`400`	Bad Request -- invalid parameters	No
`401`	Unauthorized -- missing API key	No
`403`	Forbidden -- invalid API key	No
`404`	Not Found -- unknown endpoint or resource	No
`429`	Too Many Requests -- monthly quota exceeded	No
`500`	Internal Server Error	No
`502`	Bad Gateway -- upstream service error	No
`504`	Gateway Timeout -- upstream service timed out	No

Error Response Format

All errors return a JSON object with an <code>error</code> field:

json

{
  "error": "Description of what went wrong"
}

Common Errors

Missing API Key (401)

json

{
  "message": "Forbidden"
}

Fix: Add the <code>x-api-key</code> header to every request.

Unknown Endpoint (404)

json

{
  "error": "Unknown API: nonexistent",
  "available_apis": ["enrich_profile", "enrich_company", ...]
}

Fix: Check the endpoint name. The <code>available_apis</code> list shows all valid endpoints.

Quota Exceeded (429)

json

{
  "error": "Monthly quota exceeded",
  "api": "enrich_profile",
  "limit": 100000,
  "current": 100000
}

Fix: Wait until the next month or contact us for a higher limit.

Upstream Error (502)

json

{
  "error": "Authentication with provider failed"
}

Fix: This is a server-side issue. Retry your request. If the problem persists, contact support.

Timeout (504)

json

{
  "error": "Provider timeout or connection error",
  "detail": "..."
}

Fix: The request took too long. Retry with a smaller batch size or try again later.

Retry Strategy

We recommend exponential backoff for retries:

python

import time
import requests

def call_api(url, data, api_key, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            url,
            json=data,
            headers={
                "x-api-key": api_key,
                "Content-Type": "application/json"
            }
        )

        if response.status_code == 200:
            return response.json()

        if response.status_code in (429, 502, 504):
            wait = 2 ** attempt  # 1s, 2s, 4s
            time.sleep(wait)
            continue

        # Non-retryable error
        response.raise_for_status()

    raise Exception("Max retries exceeded")