Skip to main content

​
Error Response Format

All API endpoints return errors in a consistent JSON format: 
{
  "error": "Human-readable error message",
  "details": "Additional technical details (optional)"
}
Some endpoints may include additional context-specific fields: 
{
  "error": "No tokens available to claim yet",
  "nextInflationTime": "2024-01-16T10:30:00.000Z"
}

​
HTTP Status Codes

The API uses standard HTTP status codes to indicate the type of error:
Client Error: The request was invalid or missing required parameters.Common Causes:
  • Missing required fields
  • Invalid parameter values
  • Business logic violations (e.g., claiming more tokens than available)
  • Invalid Base58 characters in addresses
Example:
{
  "error": "Missing required fields: name, symbol, and payerPublicKey are required"
}
Resource Not Found: The requested resource doesn’t exist.Common Causes:
  • Token not found in database
  • Token not launched through this API
  • Invalid transaction keys
Example:
{
  "error": "Token not found"
}
Rate Limited: Client has exceeded the request rate limit.Rate Limit: 8 requests per IP per 2-minute windowResponse:
{
  "error": "Too many requests from this IP, please try again later."
}
Handling: Implement exponential backoff and respect rate limits.
Server Error: An unexpected error occurred on the server.Common Causes:
  • Missing environment configuration
  • Blockchain network issues
  • Database connectivity problems
  • External service failures (Helius, IPFS)
Example:
{
  "error": "RPC_URL not configured"
}

​
Error Categories

​
Validation Errors (400)

Input validation and business rule violations: 
{
  "error": "Missing required parameters"
}
Solution: Check endpoint documentation for required fields.
{
  "error": "CA ending contains invalid Base58 characters (0, O, I, l)"
}
Solution: Use valid Base58 characters only.
{
  "error": "Requested amount exceeds available claim amount"
}
Solution: Check claim eligibility before creating transactions.
{
  "error": "Token keypair not found. Please call /launch first."
}
Solution: Complete the full flow within the timeout window.

​
Configuration Errors (500)

Server configuration and environment issues: 
{
  "error": "PROTOCOL_PRIVATE_KEY not configured"
}
Solution: Contact support - this is a server configuration issue.
{
  "error": "Helius API key not configured"
}
Solution: Check health endpoint and contact support if persistent.

​
Blockchain Errors (500)

Solana network and transaction issues: 
{
  "error": "Failed to confirm launch",
  "details": "Transaction simulation failed"
}
Solution: Check account balances and retry with fresh transaction.
{
  "error": "Failed to create mint transaction",
  "details": "RPC request timeout"
}
Solution: Retry request - may be temporary network congestion.

​
Best Practices

​
Error Handling Strategy

async function handleAPICall(endpoint, options) {
  try {
    const response = await fetch(endpoint, options);

    if (!response.ok) {
      const error = await response.json();

      switch (response.status) {
        case 400:
          // Handle validation errors
          showUserError(error.error);
          break;

        case 404:
          // Handle not found
          showUserError('Resource not found');
          break;

        case 429:
          // Handle rate limiting
          await exponentialBackoff();
          return handleAPICall(endpoint, options);

        case 500:
          // Handle server errors
          showUserError('Service temporarily unavailable');
          logError(error);
          break;

        default:
          showUserError('An unexpected error occurred');
      }

      throw new Error(error.error);
    }

    return await response.json();
  } catch (networkError) {
    // Handle network errors
    showUserError('Network connection failed');
    throw networkError;
  }
}

​
Exponential Backoff

Implement exponential backoff for rate limiting and transient errors: 
async function exponentialBackoff(attempt = 0, maxRetries = 5) {
  if (attempt >= maxRetries) {
    throw new Error('Max retries exceeded');
  }

  const delay = Math.min(1000 * (2 ** attempt), 30000); // Cap at 30 seconds
  const jitter = Math.random() * 1000; // Add jitter to prevent thundering herd

  await new Promise(resolve => setTimeout(resolve, delay + jitter));
}

​
User Experience

  • Show simple error messages to users
  • Log detailed errors for developers
  • Provide helpful suggestions when possible
// User sees: "Invalid token symbol"
// Log shows: "CA ending contains invalid Base58 characters (0, O, I, l)"

if (error.includes('rate limit')) {
  showMessage('Please wait before trying again. High demand detected.');
} else if (error.includes('not found')) {
  showMessage('Token not found. Please check the address and try again.');
}
  • Show loading indicators during API calls
  • Disable buttons to prevent duplicate requests
  • Provide cancel options for long operations

​
Error Prevention

​
Validation Before API Calls

// Validate inputs before making API calls
function validateLaunchData(data) {
  const errors = [];

  if (!data.name || data.name.trim().length === 0) {
    errors.push('Token name is required');
  }

  if (!data.symbol || data.symbol.trim().length === 0) {
    errors.push('Token symbol is required');
  }

  if (data.caEnding && data.caEnding.length > 3) {
    errors.push('CA ending must be 3 characters or less');
  }

  if (data.caEnding && /[0OIl]/.test(data.caEnding)) {
    errors.push('CA ending contains invalid characters');
  }

  try {
    new PublicKey(data.payerPublicKey);
  } catch {
    errors.push('Invalid payer public key');
  }

  return errors;
}

​
Debugging Tips

Always check /health when debugging configuration issues:
const health = await fetch('/health').then(r => r.json());
console.log('Environment status:', health.environment);
Track your request frequency to avoid hitting limits:
let requestCount = 0;
const startTime = Date.now();

function trackRequest() {
  requestCount++;
  const elapsed = Date.now() - startTime;
  console.log(`${requestCount} requests in ${elapsed}ms`);
}
Monitor transaction timing to avoid timeouts:
const start = Date.now();
// ... API call
const duration = Date.now() - start;
console.log(`Transaction took ${duration}ms`);
⌘I