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

# Error handling and troubleshooting

> Complete guide to DexPaprika API error codes, common issues, and troubleshooting steps for REST API and Streaming API.

## REST API errors

All REST API errors return a JSON object with a `message` field (and sometimes an `error` field). Here's every status code you can encounter:

### 200 -- Success

Normal response. Parse the JSON body.

One important edge case: **batch pricing** (`GET /networks/{network}/multi/prices`) returns HTTP 200 with an empty array `[]` when none of the requested tokens have pricing data. This is not an error -- it means the tokens were processed but none had prices.

***

### 400 -- Bad Request

The request was malformed or contained invalid parameters.

```json theme={null}
{"message": "invalid query param"}
```

**Common causes:**

* Invalid `order_by` or `sort_by` value (e.g., using `liquidity` when only `volume_usd`, `price_usd`, `transactions`, `last_price_change_usd_24h`, `created_at` are valid)
* Invalid `interval` value for OHLCV (must be one of: `1m`, `5m`, `10m`, `15m`, `30m`, `1h`, `6h`, `12h`, `24h`)
* Batch pricing with more than 10 tokens
* Batch pricing with zero tokens (empty `tokens` parameter)
* Invalid UNIX timestamp format in filter parameters
* Missing required parameters (e.g., `start` for OHLCV)

**What to do:** Check the parameter values against the [API reference](/api-reference/introduction) or [common patterns](/knowledge-base/common-patterns).

***

### 404 -- Not Found

The requested resource doesn't exist.

```json theme={null}
{"message": "not found"}
```

**Common causes:**

* Invalid network ID (e.g., `eth` instead of `ethereum`, `sol` instead of `solana`)
* Token address doesn't exist on that network
* Pool address doesn't exist on that network
* Typo in the URL path

**What to do:**

1. Verify the network ID by checking `GET /networks`
2. Use `GET /search?query={name}` to find the correct network and address
3. Check that the address format matches the chain (e.g., `0x...` for EVM chains, base58 for Solana)

***

### 410 -- Gone

The endpoint has been permanently removed.

```json theme={null}
{"error": "Endpoint Removed", "message": "This endpoint has been permanently removed. Please refer to our API documentation for alternatives."}
```

**Currently applies to:**

* `GET /pools` -- the global pools endpoint was deprecated in v1.3.0. Use `GET /networks/{network}/pools` instead.

***

### 429 -- Too Many Requests

Rate limit exceeded.

**Free tier limit:** 10,000 requests per day.

**What to do:**

* Cache responses for data that doesn't change every second (network lists, DEX lists)
* Use batch pricing instead of individual token requests
* Use the streaming API for real-time prices instead of polling
* Consider the [Pro API](/api-pro/introduction) for unlimited requests

***

### 500 -- Internal Server Error

Something went wrong on our side.

**What to do:** Retry with exponential backoff (wait 1s, then 2s, then 4s, etc.). If the error persists, check our [Discord](https://discord.gg/DhJge5TUGM) for status updates or contact support.

***

## Streaming API errors

The streaming API at `https://streaming.dexpaprika.com` can fail in two ways: HTTP errors before the stream starts, or SSE error events during an active stream.

### HTTP errors (before stream starts)

| Status | Meaning                                                                             |
| ------ | ----------------------------------------------------------------------------------- |
| 200    | Connected successfully, streaming                                                   |
| 400    | Bad parameters, unsupported chain, token not found, or one invalid asset in a batch |
| 429    | Global stream limit exceeded (10,000 concurrent streams per server)                 |

**The 400 behavior is strict:** In a POST request with multiple tokens, if even one token is invalid, the entire request fails. Validate all tokens via the REST API before streaming them.

### SSE errors (during active stream)

If something goes wrong during an active stream, the error arrives as an SSE event:

```
event: error
data: {"message": "..."}
```

**What to do:** Close the connection and reconnect with exponential backoff.

***

## Pagination gotchas

All paginated endpoints in DexPaprika are **1-indexed**:

* `page=1` returns the first page
* `page=0` is silently treated as `page=1` (not an error, but may cause confusion)

Maximum page size is 100 items (via `limit` parameter). Transaction pagination is limited to 100 pages -- for deeper history, use cursor-based pagination with the `cursor` parameter.

***

## Common mistakes and fixes

<AccordionGroup>
  <Accordion title="Getting empty results from pool listing">
    **Symptom:** `GET /networks/{network}/pools?limit=1` returns `{"pools": [], "page_info": {...}}`

    **Cause:** Some combinations of very small limits can return empty results due to internal filtering.

    **Fix:** Use `limit=10` or higher. The minimum practical limit is 2–3.
  </Accordion>

  <Accordion title="Search returns no results for a known token">
    **Symptom:** `GET /search?query=USDC` returns empty arrays.

    **Cause:** Search is best-effort and may not match very common/generic terms well. It searches across tokens, pools, and DEXes.

    **Fix:** Try more specific queries (e.g., the token address), or use the token endpoint directly if you know the network and address.
  </Accordion>

  <Accordion title="OHLCV returns empty array">
    **Symptom:** OHLCV request returns `[]`.

    **Cause:** The `start` date might be before the pool existed, or the pool may have very low activity in the requested period.

    **Fix:** Check the pool's `created_at` field to ensure your date range is valid. Try a broader interval (e.g., `24h` instead of `1h`).
  </Accordion>

  <Accordion title="Filter endpoint field names don't match pool listing">
    **Symptom:** Code that works with `/pools` breaks when switched to `/pools/filter`.

    **Cause:** Different response schemas. Filter uses `address` (not `id`), `volume_usd_24h` (not `volume_usd`), `txns_24h` (not `transactions`), and wraps results in `results` (not `pools`).

    **Fix:** Handle each endpoint's response format separately. See [common patterns](/knowledge-base/common-patterns#pattern-6-filter-pools-by-criteria) for the exact filter response structure.
  </Accordion>

  <Accordion title="Streaming connection drops immediately">
    **Symptom:** Streaming connection returns 400 instantly.

    **Cause:** One or more assets in the request are invalid (wrong chain ID, non-existent token address).

    **Fix:** Validate every token via the REST API before adding it to a streaming request. In a POST batch, all assets must be valid -- one bad asset cancels the entire stream.
  </Accordion>
</AccordionGroup>

### FAQs

<AccordionGroup>
  <Accordion title="Does DexPaprika return rate limit headers?">
    The API does not currently return standard rate limit headers (X-RateLimit-\*). Monitor your daily usage on your side.
  </Accordion>

  <Accordion title="What happens after a rate limit reset?">
    The daily limit resets on a rolling 24-hour window. After hitting the limit, wait and retry.
  </Accordion>

  <Accordion title="Are there different limits per endpoint?">
    No. The 10,000 request/day limit applies across all endpoints combined.
  </Accordion>
</AccordionGroup>

<script type="application/ld+json">
  {JSON.stringify({
      "@context": "https://schema.org",
      "@type": "FAQPage",
      "mainEntity": [
        {"@type": "Question","name": "Does DexPaprika return rate limit headers?","acceptedAnswer": {"@type": "Answer","text": "No. Monitor your daily usage on your side."}},
        {"@type": "Question","name": "What happens after a rate limit reset?","acceptedAnswer": {"@type": "Answer","text": "The daily limit resets on a rolling 24-hour window."}},
        {"@type": "Question","name": "Are there different rate limits per endpoint?","acceptedAnswer": {"@type": "Answer","text": "No. The 10,000/day limit applies across all endpoints combined."}}
      ]
    })}
</script>