Skip to main content
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.
Error Response
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.

​
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 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 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 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 and include the X-Request-ID response header value so the team can trace your specific requests in the server logs.