Error Handling

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 it persists, 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

Correct

Missing Authorization header

Wrong

Correct

Using an invalid agent_id

Wrong

Correct

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

​Error Response Format

​HTTP status codes

​Common mistakes

​Retry strategy

Error Response Format

HTTP status codes

Common mistakes

Retry strategy