Reference

Error Handling

How to interpret error responses and recover gracefully.

Error Response Format

When a request fails, the response body contains a structured error object:

Error Response

{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Parameter 'min_volume' must be a string",
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

Code	Meaning	What to Do
200	Success	Request completed. Parse data.results as usual.
400	Bad Request	Check your request body — missing agent_id, malformed JSON, or invalid param values. All params must be strings.
401	Unauthorized	Missing or invalid API token. Verify your Authorization: Bearer header.
403	Forbidden	Your token doesn't have access to this endpoint. Check your plan or contact support.
404	Not Found	Invalid agent_id or the endpoint doesn't exist. Check the API Reference for valid IDs.
429	Rate Limited	Too many requests. Back off and retry with exponential delay.
500	Server Error	Something went wrong on our end. Retry after a brief delay. If persistent, contact support with the request_id.
503	Unavailable	Service temporarily unavailable. Retry in a few seconds.

Common Mistakes

Passing numbers instead of strings in params

Wrong"min_volume": 1000

Correct"min_volume": "1000"

All param values must be strings, even numeric ones.

Missing Authorization header

Wrongcurl -X POST ... -d '{"agent_id": 574}'

Correctcurl -X POST ... -H "Authorization: Bearer YOUR_TOKEN" -d '...'

Every request requires the Bearer token header.

Using an invalid agent_id

Wrong"agent_id": 999

Correct"agent_id": 574

Check the API Reference sidebar for valid endpoint IDs.

Retry Strategy

For 429, 500, and 503 responses, use exponential backoff:

Python

import time, requests

def query(body, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(URL, json=body, headers=HEADERS)
        if resp.status_code == 200:
            return resp.json()
        if resp.status_code in (429, 500, 503):
            time.sleep(2 ** attempt)  # 1s, 2s, 4s
            continue
        resp.raise_for_status()  # 400/401/403 → fail fast