Documentation

Error Handling

Reference

Common errors, revert reasons, and retry strategies for API and on-chain operations.

HTTP Error Codes

400

Bad Request

Validation error. Check required fields: name, symbol, description, category, chainId.

401

Unauthorized

Invalid or missing API key. Get one at agentverse.ai/profile/api-keys.

404

Not Found

Token or resource doesn't exist. Verify the address or ID.

409

Conflict

Duplicate token name or symbol. Choose different values.

500

Server Error

Internal error. Retry with exponential backoff.

Smart Contract Revert Reasons

Insufficient allowance

User hasn't approved enough FET for the deployer contract. Need 120 FET + buyAmount.

Token already deployed

This tokenId has already been deployed on-chain. Each token can only be deployed once.

Invalid token ID

The tokenId doesn't match a valid backend record. Ensure the ID from the API response.

Max wallet exceeded

Purchase would exceed the max wallet limit for this token (if configured).

Token is listed

Token has graduated to DEX. Trade on Uniswap/PancakeSwap instead.

Retry Strategy

import time
import requests

def api_call_with_retry(url, method="GET", **kwargs):
    max_retries = 3
    base_delay = 1  # seconds

    for attempt in range(max_retries):
        try:
            response = requests.request(method, url, **kwargs)

            # Success
            if response.status_code < 400:
                return response.json()

            # Don't retry client errors (except 429)
            if 400 <= response.status_code < 500:
                if response.status_code == 429:
                    # Rate limited - wait longer
                    time.sleep(base_delay * (2 ** attempt) * 2)
                    continue
                raise Exception(f"Client error: {response.status_code}")

            # Server error - retry with backoff
            if response.status_code >= 500:
                time.sleep(base_delay * (2 ** attempt))
                continue

        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(base_delay * (2 ** attempt))

    raise Exception("Max retries exceeded")

Best Practices

Do

Use exponential backoff for retries
Check approval before contract calls
Validate inputs before API calls
Log errors with full context
Handle rate limits gracefully

Don't

Retry indefinitely
Ignore error responses
Retry 4xx errors (except 429)
Use fixed delays for retries
Swallow exceptions silently