> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dexutils.io/llms.txt
> Use this file to discover all available pages before exploring further.
# DexUtils API Error Codes and Troubleshooting Guide
> Understand DexUtils API HTTP status codes, error response format, and how to resolve common errors including 401, 403, 404, and 429.
When something goes wrong, the DexUtils API always returns a structured JSON error body alongside the appropriate HTTP status code. This makes it straightforward to handle errors programmatically, surface meaningful messages to your users, and diagnose issues quickly without having to parse freeform text.
## Error Response Format
Every error response follows the same envelope structure. The `code` field is a machine-readable string you can match against in your error-handling logic, while `message` provides a human-readable explanation.
```json Error Response theme={null}
{
"error": {
"code": "INVALID_API_KEY",
"message": "The provided API key is invalid or has been revoked.",
"status": 401
}
}
```
Never log raw request headers or full error responses to publicly accessible log streams. Your `Authorization` header contains your API key — if it appears in logs, rotate the key immediately from **Settings → API Keys**.
## Error Code Reference
The table below covers every error code the API can return, what causes it, and how to resolve it.
| HTTP Status | Error Code | Description | Resolution |
| ----------- | --------------------- | --------------------------------------- | -------------------------------------------------------------- |
| 400 | `BAD_REQUEST` | Invalid query parameters | Check parameter types and allowed values |
| 401 | `INVALID_API_KEY` | Missing or invalid Authorization header | Verify your key format: `Bearer YOUR_API_KEY` |
| 401 | `MISSING_AUTH` | No Authorization header provided | Add `Authorization: Bearer YOUR_API_KEY` header |
| 403 | `KEY_EXPIRED` | API key has expired | Regenerate your key in **Settings → API Keys** |
| 403 | `PLAN_REQUIRED` | Endpoint requires Pro plan | Upgrade your plan to access this endpoint |
| 404 | `NOT_FOUND` | Token, pool, or network not found | Verify the address and network ID are correct |
| 422 | `INVALID_ADDRESS` | Contract address format is invalid | Use a checksummed EVM address or valid Solana pubkey |
| 429 | `RATE_LIMITED` | Daily request quota exceeded | Wait for quota reset or upgrade to Pro |
| 500 | `INTERNAL_ERROR` | Server-side error | Retry with exponential backoff; contact support if it persists |
| 503 | `SERVICE_UNAVAILABLE` | Temporary maintenance | Retry after a short delay |
## Troubleshooting Common Errors
This error means the API key you provided either does not exist in our system or has been revoked.
**Steps to resolve:**
1. Open your dashboard and navigate to **Settings → API Keys**.
2. Confirm the key you are using matches the one listed (they are partially masked — copy a fresh one if unsure).
3. Check that your `Authorization` header is formatted exactly as `Bearer YOUR_API_KEY` with a single space between `Bearer` and the key and no trailing whitespace.
4. If you recently rotated your key, make sure all environments and services have been updated to use the new value.
5. If the key appears correct but the error persists, revoke it and generate a new one.
This error means the endpoint you are calling is restricted to Pro API plan subscribers and is not available on your current plan.
**Steps to resolve:**
1. Review the endpoint's documentation to confirm which plan tier is required.
2. Navigate to **Settings → Plan & Billing** to review your current plan and upgrade options.
3. If you recently upgraded, allow a few minutes for your new plan permissions to propagate, then retry the request.
This error means the token address you supplied does not exist in our index for the specified network.
**Steps to resolve:**
1. Double-check the contract address against a block explorer (Etherscan, BscScan, etc.) to confirm it is a valid token contract.
2. Make sure you are querying the correct network. A token address on Ethereum will not resolve on BNB Chain, even if the address string looks valid.
3. Newly deployed tokens can take up to five minutes to appear in the index after their first on-chain trade.
4. Use the `GET /search` endpoint to look up a token by symbol or name if you are unsure of the exact address.
This error means the `{network}` path segment you provided does not match any supported network slug.
**Steps to resolve:**
1. Fetch the full list of supported networks and their slugs by calling `GET /networks`.
2. Use the `id` field from that response as the `{network}` path parameter — for example, `ethereum`, `bsc`, `solana`.
3. Network slugs are lowercase and use underscores, not hyphens (e.g., `arbitrum_one`, not `arbitrum-one`).
This error means the address string you passed is syntactically malformed and cannot be resolved to a contract, regardless of which network you queried.
**Steps to resolve:**
1. For EVM networks (Ethereum, BNB Chain, Polygon, Arbitrum, etc.), ensure the address is a 42-character hexadecimal string starting with `0x`. Checksummed (mixed-case) addresses are accepted; lowercase is also valid.
2. For Solana, ensure the address is a valid Base58-encoded public key (typically 32–44 characters).
3. Check for common copy-paste issues: extra spaces, truncated strings, or characters from a surrounding URL.
4. Use the `GET /search` endpoint to find the canonical address for a token or pool if you only have a name or symbol.
Your account has consumed all of its allocated requests for the current UTC day. The API will reject further requests until the quota resets.
**Steps to resolve:**
1. Check the `X-RateLimit-Reset` response header for the Unix timestamp when your quota resets (always midnight UTC).
2. Review the `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers on your previous responses — if you were not monitoring them, start doing so to add proactive throttling to your code.
3. Reduce redundant requests by caching responses and using `POST /tokens/batch` for multi-token lookups.
4. Upgrade to the Pro API plan for unlimited requests with no daily or per-minute caps.
This error indicates an unexpected failure on the DexUtils API server. It is not caused by your request parameters.
**Steps to resolve:**
1. Retry the request using exponential backoff — most transient server errors resolve within one or two retries.
2. Check the [DexUtils Status Page](https://status.dexutils.io) for any active incidents that may be affecting the API.
3. If the error persists across multiple retries and no incident is reported, contact **[support@dexutils.io](mailto:support@dexutils.io)** and include the `X-Request-ID` response header value so the support team can trace your request in the server logs.
This error means the API or a specific service it depends on is temporarily unavailable, typically due to a scheduled maintenance window or an unplanned outage.
**Steps to resolve:**
1. Check the [DexUtils Status Page](https://status.dexutils.io) for active maintenance windows or ongoing incidents.
2. Retry the request after a short delay — maintenance windows are typically brief and completed within minutes.
3. Implement exponential backoff in your integration so that brief outages are handled automatically without manual intervention.
If you receive repeated `500 INTERNAL_ERROR` responses that are not resolved by retrying, please contact support at **[support@dexutils.io](mailto:support@dexutils.io)** and include the `X-Request-ID` response header value so the team can trace your specific requests in the server logs.