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

# Troubleshooting

> Fixes for common Codex API problems: authentication errors, WebSocket and subscription errors, GraphQL validation errors, and null or empty results.

> [!TIP]
>
> Can't find your issue here? Try our integrated AI assistant at the top of the page, or reach out on [Discord](https://discord.com/invite/9ZB7zcWuBY).

## Authentication Errors

For HTTP 402, 502, 503 and HTML 403 "Request blocked" responses, see [Errors & Retries](https://docs.codex.io/concepts/errors.md#which-errors-to-retry).

> [accordion] Error: "Your API key was not found" / UNAUTHENTICATED / 401
>
> Your API key is missing, invalid, or expired.
>
> **Fixes:**
>
> * Verify you're passing the key in the `Authorization` header: `"Authorization": "your-api-key"`
> * For short-lived tokens (JWTs), use the `Bearer` prefix: `"Authorization": "Bearer <token>"`
> * Check that your key hasn't been deactivated on the [dashboard](https://dashboard.codex.io)
> * If using the SDK, ensure you're passing the key correctly: `new Codex("your-api-key")`
>
> ```typescript theme={null}
> // Secret key — no prefix needed
> fetch("https://graph.codex.io/graphql", {
>   headers: { "Authorization": "your-api-key" }
> })
>
> // Short-lived token — Bearer prefix required
> fetch("https://graph.codex.io/graphql", {
>   headers: { "Authorization": "Bearer eyJhbGciOi..." }
> })
> ```

> [accordion] "Not authorized: please upgrade your plan"
>
> You're trying to use a feature that isn't available on your current plan. Common cases:
>
> * **`holders` query** — requires a Growth or Enterprise plan
> * **WebSocket subscriptions** — require a Growth or Enterprise plan
> * **`tokenTopTraders`** — requires a Growth or Enterprise plan
>
> Upgrade your plan on the [billing page](https://dashboard.codex.io/dashboard/billing?utm_source=codex\&utm_medium=docs\&utm_campaign=troubleshooting).

> [accordion] Previously working API key suddenly returns errors
>
> * Check that you haven't exceeded your plan's monthly request limit — overages are charged at the same rate as your plan
> * Verify the key is still active on the [dashboard](https://dashboard.codex.io)
> * If using a short-lived token, it may have expired — generate a new one with `createApiTokens`

## WebSocket & Subscription Errors

> [accordion] Socket closed with event 4403 Forbidden
>
> The server rejected your WebSocket connection. Common causes:
>
> * **Wrong plan:** Subscriptions require a Growth or Enterprise plan
> * **Missing auth:** You must pass your API key in the `connection_init` payload, not as a URL parameter
> * **Exceeded connection limit:** Growth plans are limited to 300 concurrent WebSocket connections
>
> ```typescript theme={null}
> // Correct — auth in connection_init payload
> const client = createClient({
>   url: "wss://graph.codex.io/graphql",
>   connectionParams: {
>     Authorization: "your-api-key",
>   },
> });
> ```

> [accordion] Socket closed with event 4401 / Subscribing before connection\_ack
>
> You're sending a `subscribe` message before the server has acknowledged your connection. You **must** wait for the `connection_ack` message before subscribing.
>
> ```javascript theme={null}
> webSocket.onmessage = (event) => {
>   const data = JSON.parse(event.data);
>   if (data.type === "connection_ack") {
>     // Only NOW is it safe to subscribe
>     webSocket.send(JSON.stringify({
>       id: "1",
>       type: "subscribe",
>       payload: { query: "subscription { ... }" }
>     }));
>   }
> };
> ```
>
> If you're using the [SDK](https://docs.codex.io/sdk.md) or `graphql-ws`, this is handled automatically.

> [accordion] WebSocket disconnects after a period of inactivity
>
> Connections require periodic heartbeat messages to stay alive.
>
> * **SDK users:** Heartbeats are handled automatically
> * **Custom implementations:** Send a `ping` message periodically. See the [graphql-ws protocol](https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md#ping) for details

> [accordion] 403 errors appearing intermittently on an active subscription
>
> If your connection works initially but starts returning 403 errors:
>
> * You may have hit your plan's connection limit (300 for Growth plans) — check if you have stale connections that weren't properly closed
> * Ensure you close subscriptions and connections when they're no longer needed
> * Deactivating an API key does **not** close active subscriptions — they persist until disconnected

> [accordion] I can't send queries through WebSockets — only subscriptions work
>
> Correct — WebSocket connections are for subscriptions (real-time updates) only. Use HTTP POST requests to `https://graph.codex.io/graphql` for queries and mutations. See the [Subscriptions concept](https://docs.codex.io/concepts/subscriptions.md) for more details.

## GraphQL Validation Errors

These errors mean your query has a field or argument that doesn't exist on the type you're querying. The error message tells you exactly what's wrong.

> [accordion] Cannot query field "isVerified" on type "EnhancedToken"
>
> There is no `isVerified` response field. Codex uses `isScam` instead — `isScam: false` is the equivalent of a token being "verified."
>
> * **To filter** for verified tokens: use `isVerified: true` in `filterTokens` filters
> * **To read** verification status: use `isScam` on the token object
>
> ```graphql theme={null}
> # Filter for verified tokens
> query {
>   filterTokens(filters: { isVerified: true }) {
>     results {
>       token {
>         name
>         isScam  # false = verified
>       }
>     }
>   }
> }
> ```
>
> See the [FAQ](https://docs.codex.io/extra/faq.md#data-coverage--methodology) for more details.

> [accordion] Cannot query field "X" on type "Y" — general fix
>
> This means the field doesn't exist on the type. Common mistakes:
>
> | You wrote | Fix |
> | - | - |
> | `token { marketCap }` | `marketCap` is on `TokenFilterResult`, not `EnhancedToken`. Use `filterTokens` to get it |
> | `token { priceChange5m }` | `priceChange5m` is only on `PairMetadata`. `TokenFilterResult` has `priceChange1`/`4`/`12`/`24` but not `5m` |
> | `pair { factoryAddress }` | `factoryAddress` is not a field on `Pair` |
> | `detailedPairStats { pairId }` | Use `pairAddress` instead |
> | `tokenInfo { thumbHashUrl }` | Use `imageThumbUrl` instead |
>
> Use our [explorer](https://explorer.codex.io) which has autocomplete to discover available fields, or browse the [GraphQL Reference](https://docs.codex.io/api-reference/introduction.md).

> [accordion] Unknown argument "inputs" on field — Did you mean "input"?
>
> Some fields use `input` (singular) while others use `inputs` (plural). Check the exact parameter name in the [API reference](https://docs.codex.io/api-reference/introduction.md).
>
> Common ones:
>
> * `onPricesUpdated` uses `input` (singular) containing a list of tokens
> * `getTokenPrices` uses `inputs` (plural)
> * `token` uses `input` (singular)

> [accordion] Unknown argument "rankings" on field "Query.filterTokenWallets"
>
> `filterTokenWallets` does not support a `rankings` argument. It uses `filters` and pagination parameters (`cursor`, `limit`). Only `filterTokens` and `filterPairs` support `rankings`.

> [accordion] Field "token0" must not have a selection since type "String!" has no subfields
>
> On the `Pair` type, `token0` and `token1` are strings (token addresses), not objects. If you want token metadata from a pair query, use `pairMetadata` with `enhancedToken0` / `enhancedToken1` instead.
>
> ```graphql theme={null}
> # Wrong — token0 is a String on Pair
> pair { token0 { name symbol } }
>
> # Right — use pairMetadata for enriched token data
> pairMetadata(pairId: "...") {
>   enhancedToken0 { name symbol }
>   enhancedToken1 { name symbol }
> }
> ```

> [accordion] GraphQL syntax errors (IDENT, LBRACE, COLON)
>
> These are query syntax errors, usually from:
>
> * **Missing colons** between field names and arguments — `unexpected token - got: IDENT want one of: [COLON]`
> * **Template literals not rendering** — if you're using a tool like n8n, Make, or Retool, ensure your template syntax (`{{ }}`) isn't conflicting with GraphQL
> * **Missing closing braces** — count your `{` and `}` to make sure they match
>
> Test your query in the [explorer](https://explorer.codex.io) first to verify the syntax is correct before using it in code.

## Null or Empty Results

> [accordion] getTokenPrices returns \[null] for a token
>
> Common causes:
>
> * **Token hasn't traded yet** — Codex only has price data for tokens with trading activity
> * **Pre-graduation launchpad token** — bonding curve tokens may not have a price available via `getTokenPrices`. Use `onLaunchpadTokenEventBatch` for launchpad token prices, or `filterTokens` which includes `priceUSD` for launchpad tokens
> * **Wrong address format** — for Tron, use the hex (0x) address, not the base58 (T...) address
> * **Wrong networkId** — verify you're using the correct network ID for the chain

> [accordion] filterTokens returns empty results
>
> * **Filters too narrow** — loosen your filters and add them back one at a time to identify which one is excluding results
> * **Launchpad graduation filters** — `launchpadGraduationPercent` uses `gt`/`lt`/`gte`/`lte`, make sure your range isn't excluding everything (e.g., `gt: 100` won't match anything since graduation maxes at 100)
> * **Missing network filter** — without a `network` filter, results come from all chains which may dilute what you expect
> * **Scam filtering** — tokens flagged as potential scams are excluded by default. Add `includeScams: true` to include them

> [accordion] Null fields in subscription responses (balanceUsd, socialLinks, etc.)
>
> Some fields can legitimately be `null`:
>
> * **`balanceUsd`** in `onBalanceUpdated` — may be null if the token doesn't have a price yet
> * **`socialLinks`** (twitter, telegram, website) — not all tokens have social links. We source these from 10+ providers but they may not be available for newer tokens
> * **`mintable` / `freezable`** — a `null` value could mean either "not mintable" or "we don't have this data." Check `isMintableValid` / `isFreezableValid` to distinguish between the two
> * **`circulatingSupply`** — may be null for tokens where we haven't been able to determine circulating supply

> [accordion] getTokenBars / getBars returns null
>
> * Verify the `from` and `to` timestamps are Unix timestamps (seconds, not milliseconds)
> * Check that the token/pair had trading activity during the requested time range
> * `getTokenBars` has limited historical data — it may not cover older time ranges
> * For older historical data, use `getBars` with a specific pair address instead

> [accordion] getDetailedPairStats returns null for some pairs
>
> Not all pairs have detailed stats available. This typically happens with very low volume or newly created pairs. Try querying a different pair for the same token using `listPairsWithMetadataForToken`.

> [accordion] getTokenEvents returns null / DOWNSTREAM\_SERVICE\_ERROR
>
> * `getTokenEvents` queries the top pair by default — if the token has multiple pairs, events on other pairs won't appear. Use `listPairsWithMetadataForToken` to find all pairs
> * If you're getting a `DOWNSTREAM_SERVICE_ERROR`, this is usually a temporary issue. Retry after a few seconds
> * Verify the token address and networkId are correct

> [accordion] filterTokenWallets returns empty results for a wallet that holds the token
>
> `filterTokenWallets` only tracks wallets that acquired tokens via DEX swaps. If a wallet received tokens via a direct transfer (not a swap), it won't appear in results. Use the `balances` query instead for a complete view of token holdings.

## Connection Limits & Rate Limits

> [accordion] How many WebSocket connections can I have?
>
> Growth plans support up to 300 concurrent WebSocket connections. Enterprise has no hard limit — contact us for guidance. For full guidance on capacity per connection, see [Rate Limits & Connection Limits](https://docs.codex.io/concepts/rate-limits.md) and [Subscriptions](https://docs.codex.io/concepts/subscriptions.md).

> [accordion] How do connections vs subscriptions work?
>
> * A **connection** is a single WebSocket to `wss://graph.codex.io/graphql`
> * A **subscription** is a single `subscribe` message on that connection (e.g., one `onPriceUpdated` for one token)
> * You can run multiple subscriptions on one connection — just send additional `subscribe` messages
> * Some subscriptions accept multiple tokens (e.g., `onPricesUpdated` can watch up to 25 tokens)
>
> See [Subscriptions](https://docs.codex.io/concepts/subscriptions.md) for full details.

> [accordion] HTTP 400 from too many items in a batch request
>
> Some queries have limits on array inputs:
>
> * `getTokenPrices` — max 25 tokens per request; extra inputs are dropped without an error
> * `filterTokens` — max 200 results per request
> * `tokens`: max 100 ids per request
> * `getDetailedPairsStats`: max 10 inputs per request (extra inputs are dropped)
> * `filterWallets`: max 100 wallet addresses and `limit` 100
>
> Split large requests into smaller batches. See [Per-Request Limits](https://docs.codex.io/concepts/rate-limits.md#per-request-limits) for the full list.

> [accordion] What are the rate limits?
>
> Rate limits depend on your plan. See [Rate Limits & Connection Limits](https://docs.codex.io/concepts/rate-limits.md) for the full breakdown by plan and tips on optimizing usage. If you're consistently hitting rate limits, also see [Optimization](https://docs.codex.io/concepts/optimization.md).

> [accordion] HTTP 429 — how long should I wait before retrying?
>
> Read `extensions.retryAfterSeconds` on the error and wait that many seconds. The same value is sent as the `Retry-After` header, so most HTTP clients can honor it automatically.
>
> If the 429 has no `retryAfterSeconds`, your request budget is momentarily empty rather than your account being throttled — capacity usually returns within a second. Use your own backoff rather than retrying immediately.
>
> A fixed retry interval that's shorter than the penalty window will land every retry inside it and keep you rate limited. See [Errors & Retries](https://docs.codex.io/concepts/errors.md).

> [accordion] OVER\_CAPACITY in my response
>
> We're briefly over capacity and scaling up. The error carries `extensions.retryAfterSeconds` — wait that long and retry.
>
> Note this arrives as **HTTP 200** with the error in the response body, since the request itself was valid. Retry logic that only checks HTTP status codes will miss it and won't back off. See [Errors & Retries](https://docs.codex.io/concepts/errors.md).

## Data Discrepancies

> [accordion] Liquidity values are lower than other platforms
>
> Codex reports the liquidity of the **base token side** of the pool only. Other platforms typically double this by including both sides. To get the "total" liquidity, add both pooled amounts together. We report single-sided liquidity because we believe it more accurately represents the actual backing.

> [accordion] Prices differ from DexScreener / Birdeye / other platforms
>
> Codex chart prices reflect the **current pool price** (based on reserves), not the last executed trade price. Other platforms often show the last trade price. Both are valid — they just measure different things. Trade prices for individual transactions are available in `getTokenEvents`.
>
> Note: this also explains why event prices and chart prices differ for the same token — events show the executed price of the transaction, while the chart shows the current pool price.

> [accordion] Tron tokens returning no data
>
> Codex requires the hex (ERC20) address format for Tron tokens, not the base58 format shown on Tron explorers.
>
> * Base58: `TXYZabc123...` (what you see on explorers)
> * Hex: `0x41abc123...` (what Codex requires)
>
> Convert between formats using: [https://tronweb.network/docu/docs/API%20List/utils/address/](https://tronweb.network/docu/docs/API%20List/utils/address/)

> [accordion] Native tokens (ETH, SOL, BNB) — which address to use?
>
> Codex uses the **wrapped** versions of native tokens (WETH, WSOL, WBNB). Prices are 1:1 with the native token. Use the wrapped token address in your queries.

## Still Stuck?

* Test your queries in the [explorer](https://explorer.codex.io) — it has autocomplete and will show validation errors instantly
* Browse the [GraphQL Reference](https://docs.codex.io/api-reference/introduction.md) for exact field names and types
* Check the [FAQ](https://docs.codex.io/extra/faq.md) for questions about data coverage and best practices
* Ask on [Discord](https://discord.com/invite/9ZB7zcWuBY) — the team and community are active


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