> ## Documentation Index
> Fetch the complete documentation index at: https://api.polymarketanalytics.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> How to interpret error responses and how you can recover.

## Error Response Format

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

```json Error Response theme={null}
{
  "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

<pre>
  `"min_volume": 1000`
</pre>

Correct

<pre>
  `"min_volume": "1000"`
</pre>

All param values must be strings, even numeric ones.

Missing Authorization header

Wrong

<pre>
  `curl -X POST ... -d '{"agent_id": 574}'`
</pre>

Correct

<pre>
  `curl -X POST ... -H "Authorization: Bearer YOUR_TOKEN" -d '...'`
</pre>

Every request requires the Bearer token header.

Using an invalid agent\_id

Wrong

<pre>
  `"agent_id": 999`
</pre>

Correct

<pre>
  `"agent_id": 574`
</pre>

Check the API Reference sidebar for valid endpoint IDs.

## Retry strategy

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

```python Python theme={null}
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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.