Error Handling

Comprehensive guide to handling errors in the vision.meme API. Learn about error codes, formats, and best practices for robust integration.

---

Error Response Format

All errors follow a consistent JSON structure:

Standard Error

json

{
  "error": "Error message describing what went wrong"
}

Error with Details

json

{
  "error": "Validation error",
  "details": [
    {
      "path": ["fieldName"],
      "message": "Specific error message"
    }
  ]
}

Error with Additional Context

json

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again in 300 seconds.",
  "retryAfter": 300
}

---

HTTP Status Codes

2xx Success

Code	Name	Description
200	OK	Request successful
201	Created	Resource created successfully

4xx Client Errors

Code	Name	Description	Common Causes
400	Bad Request	Invalid request	Missing fields, invalid format, validation errors
401	Unauthorized	Authentication failed	Missing token, expired token, invalid token
403	Forbidden	Not authorized	Wrong wallet, insufficient permissions
404	Not Found	Resource doesn't exist	Invalid mint address, deleted token
429	Too Many Requests	Rate limit exceeded	Too many requests in time window

5xx Server Errors

Code	Name	Description	Action
500	Internal Server Error	Server error	Retry request, contact support if persists
503	Service Unavailable	Service temporarily down	Retry with backoff

---

Common Errors

Authentication Errors

Missing Authorization Header

Status: 401 Unauthorized

json

{
  "error": "Unauthorized",
  "message": "Authorization header is required"
}

Solution:

javascript

// ❌ Missing header
fetch('https://api.vision.meme/tokens/me')

// ✅ Include header
fetch('https://api.vision.meme/tokens/me', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})

Invalid or Expired Token

Status: 401 Unauthorized

json

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

Solution:

javascript

if (response.status === 401) {
  // Re-authenticate
  token = await authenticate(walletAddress, signMessage);
  // Retry request with new token
}

Challenge Expired

Status: 400 Bad Request

json

{
  "error": "Challenge expired",
  "message": "The challenge has expired. Please request a new one."
}

Solution:

• Request a new challenge

• Complete signing within 5 minutes

---

Validation Errors

Missing Required Fields

Status: 400 Bad Request

json

{
  "error": "Validation error",
  "details": [
    {
      "path": ["name"],
      "message": "String must contain at least 1 character(s)"
    },
    {
      "path": ["symbol"],
      "message": "Required"
    }
  ]
}

Solution:

javascript

// ❌ Missing required fields
{
  "description": "My token"
}

// ✅ Include all required fields
{
  "name": "My Token",
  "symbol": "MTK",
  "description": "My token",
  "imageUri": "https://ipfs.io/ipfs/..."
}

Invalid Field Values

Status: 400 Bad Request

json

{
  "error": "Validation error",
  "details": [
    {
      "path": ["transferFeePercent"],
      "message": "Number must be greater than or equal to 0 and less than or equal to 100"
    }
  ]
}

Solution:

javascript

// ❌ Invalid value
{
  "transferFeePercent": 150 // Over 100%
}

// ✅ Valid value
{
  "transferFeePercent": 5 // Between 0-100
}

Invalid Wallet Address

Status: 400 Bad Request

json

{
  "error": "Validation error",
  "details": [
    {
      "path": ["developerWallet"],
      "message": "Invalid Solana wallet address"
    }
  ]
}

Solution:

javascript

import { PublicKey } from '@solana/web3.js';

function validateWalletAddress(address) {
  try {
    new PublicKey(address);
    return true;
  } catch {
    return false;
  }
}

if (!validateWalletAddress(developerWallet)) {
  throw new Error('Invalid wallet address');
}

---

Resource Errors

Token Not Found

Status: 404 Not Found

json

{
  "error": "Token not found"
}

Solution:

javascript

const response = await fetch(`https://api.vision.meme/tokens/${mintAddress}`);

if (response.status === 404) {
  console.log('Token does not exist or has been deleted');
  // Handle missing token
}

Forbidden Access

Status: 403 Forbidden

json

{
  "error": "Forbidden",
  "message": "You are not authorized to access this resource"
}

Causes:

• Trying to update someone else's token

• Wrong wallet authenticated

• Insufficient permissions

Solution:

javascript

// Make sure you're authenticated with the correct wallet
const creatorWallet = await getTokenCreator(tokenId);
if (currentWallet !== creatorWallet) {
  throw new Error('Must be token creator to update settings');
}

---

Rate Limit Errors

Rate Limit Exceeded

Status: 429 Too Many Requests

json

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again in 300 seconds.",
  "retryAfter": 300
}

Headers:

http

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704124800
Retry-After: 300

Solution:

javascript

async function handleRateLimit(response) {
  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After')) || 60;
    console.log(`Rate limited. Waiting ${retryAfter} seconds...`);
    
    await sleep(retryAfter * 1000);
    return true; // Retry
  }
  return false; // Don't retry
}

---

Transaction Errors

Transaction Expired

Status: 400 Bad Request

json

{
  "error": "Transaction expired",
  "message": "The unsigned transaction has expired. Please create a new one."
}

Causes:

• Took more than 5 minutes to sign transaction

• Network delays

Solution:

javascript

// Create new transaction if expired
try {
  await submitTransaction(signedTx);
} catch (error) {
  if (error.message.includes('expired')) {
    console.log('Transaction expired, creating new one...');
    const newTx = await createUnsignedTransaction();
    const newSignedTx = await signTransaction(newTx);
    await submitTransaction(newSignedTx);
  }
}

Invalid Transaction

Status: 400 Bad Request

json

{
  "error": "Invalid transaction",
  "message": "The transaction signature is invalid or transaction is malformed"
}

Solutions:

• Verify transaction was signed correctly

• Check transaction format

• Ensure no modifications after signing

---

File Upload Errors

File Too Large

Status: 400 Bad Request

json

{
  "error": "File too large",
  "message": "Image must be smaller than 1MB"
}

Solution:

javascript

function validateFileSize(file, maxSizeMB = 1) {
  const maxBytes = maxSizeMB * 1024 * 1024;
  if (file.size > maxBytes) {
    throw new Error(`File size (${(file.size / 1024 / 1024).toFixed(2)}MB) exceeds ${maxSizeMB}MB limit`);
  }
}

// Usage
validateFileSize(imageFile);
await uploadImage(imageFile);

Invalid File Type

Status: 400 Bad Request

json

{
  "error": "Invalid file type",
  "message": "Only PNG and JPG images are supported"
}

Solution:

javascript

function validateFileType(file) {
  const allowedTypes = ['image/png', 'image/jpeg', 'image/jpg'];
  if (!allowedTypes.includes(file.type)) {
    throw new Error(`Invalid file type: ${file.type}`);
  }
}

validateFileType(imageFile);

---

Error Handling Patterns

Basic Try-Catch

javascript

async function fetchToken(mintAddress) {
  try {
    const response = await fetch(`https://api.vision.meme/tokens/${mintAddress}`);
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error || 'Request failed');
    }
    
    return await response.json();
  } catch (error) {
    console.error('Failed to fetch token:', error);
    throw error;
  }
}

Comprehensive Error Handling

javascript

async function fetchTokenWithHandling(mintAddress) {
  try {
    const response = await fetch(`https://api.vision.meme/tokens/${mintAddress}`, {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    });
    
    // Handle specific status codes
    if (response.status === 401) {
      console.log('Authentication failed, re-authenticating...');
      await authenticate();
      return fetchTokenWithHandling(mintAddress); // Retry
    }
    
    if (response.status === 404) {
      console.log('Token not found');
      return null;
    }
    
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After')) || 60;
      console.log(`Rate limited. Retrying in ${retryAfter} seconds...`);
      await sleep(retryAfter * 1000);
      return fetchTokenWithHandling(mintAddress); // Retry
    }
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error || `Request failed with status ${response.status}`);
    }
    
    return await response.json();
    
  } catch (error) {
    // Handle network errors
    if (error.name === 'TypeError' && error.message === 'Failed to fetch') {
      console.error('Network error. Check your connection.');
      throw new Error('Network error');
    }
    
    console.error('Error fetching token:', error);
    throw error;
  }
}

Error Handler Class

javascript

class APIError extends Error {
  constructor(status, error, details = null) {
    super(error);
    this.status = status;
    this.details = details;
    this.name = 'APIError';
  }
  
  isValidationError() {
    return this.status === 400 && this.details;
  }
  
  isAuthError() {
    return this.status === 401;
  }
  
  isRateLimitError() {
    return this.status === 429;
  }
  
  isNotFoundError() {
    return this.status === 404;
  }
}

async function apiRequest(url, options = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      ...options.headers
    }
  });
  
  if (!response.ok) {
    const errorData = await response.json();
    throw new APIError(
      response.status,
      errorData.error,
      errorData.details
    );
  }
  
  return response.json();
}

// Usage
try {
  const token = await apiRequest('https://api.vision.meme/tokens/mint123');
} catch (error) {
  if (error instanceof APIError) {
    if (error.isValidationError()) {
      console.log('Validation errors:', error.details);
    } else if (error.isAuthError()) {
      console.log('Authentication required');
      await reauthenticate();
    } else if (error.isRateLimitError()) {
      console.log('Rate limited');
      await handleRateLimit();
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

---

Retry Strategies

Simple Retry with Delay

javascript

async function retryRequest(fn, retries = 3, delay = 1000) {
  for (let i = 0; i < retries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === retries - 1) throw error;
      
      console.log(`Attempt ${i + 1} failed, retrying in ${delay}ms...`);
      await sleep(delay);
    }
  }
}

// Usage
const result = await retryRequest(
  () => fetch('https://api.vision.meme/tokens/mint123').then(r => r.json()),
  3,
  2000
);

Exponential Backoff

javascript

async function retryWithBackoff(fn, maxRetries = 5, baseDelay = 1000) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      const delay = baseDelay * Math.pow(2, i); // Exponential
      const jitter = Math.random() * 1000; // Add randomness
      const waitTime = delay + jitter;
      
      console.log(`Retry ${i + 1}/${maxRetries} after ${waitTime}ms`);
      await sleep(waitTime);
    }
  }
}

Conditional Retry

javascript

async function retryConditionally(fn, shouldRetry, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1 || !shouldRetry(error)) {
        throw error;
      }
      
      console.log('Retryable error, attempting again...');
      await sleep(1000 * (i + 1));
    }
  }
}

// Usage
const result = await retryConditionally(
  () => fetchToken(mintAddress),
  (error) => error.status === 500 || error.status === 503, // Only retry server errors
  3
);

---

Validation Before Requests

Validate data before making requests to avoid errors:

Token Creation Validation

javascript

function validateTokenCreation(data) {
  const errors = [];
  
  // Name
  if (!data.name || data.name.length === 0) {
    errors.push({ field: 'name', message: 'Name is required' });
  } else if (data.name.length > 32) {
    errors.push({ field: 'name', message: 'Name must be 32 characters or less' });
  }
  
  // Symbol
  if (!data.symbol || data.symbol.length === 0) {
    errors.push({ field: 'symbol', message: 'Symbol is required' });
  } else if (data.symbol.length > 10) {
    errors.push({ field: 'symbol', message: 'Symbol must be 10 characters or less' });
  }
  
  // Transfer fee
  if (data.transferFeePercent < 0 || data.transferFeePercent > 100) {
    errors.push({ field: 'transferFeePercent', message: 'Must be between 0 and 100' });
  }
  
  // Developer fee
  if (data.developerFeePercent < 0 || data.developerFeePercent > 100) {
    errors.push({ field: 'developerFeePercent', message: 'Must be between 0 and 100' });
  }
  
  // Wallet address
  try {
    new PublicKey(data.developerWallet);
  } catch {
    errors.push({ field: 'developerWallet', message: 'Invalid Solana address' });
  }
  
  return errors;
}

// Usage
const errors = validateTokenCreation(tokenData);
if (errors.length > 0) {
  console.error('Validation errors:', errors);
  throw new Error('Invalid token data');
}

await createToken(tokenData);

---

Logging and Monitoring

Request Logging

javascript

class APIClient {
  async request(url, options = {}) {
    const startTime = Date.now();
    const requestId = Math.random().toString(36).substring(7);
    
    console.log(`[${requestId}] ${options.method || 'GET'} ${url}`);
    
    try {
      const response = await fetch(url, options);
      const duration = Date.now() - startTime;
      
      console.log(`[${requestId}] ${response.status} (${duration}ms)`);
      
      if (!response.ok) {
        const error = await response.json();
        console.error(`[${requestId}] Error:`, error);
        throw error;
      }
      
      return await response.json();
    } catch (error) {
      const duration = Date.now() - startTime;
      console.error(`[${requestId}] Failed (${duration}ms):`, error);
      throw error;
    }
  }
}

Error Tracking

javascript

class ErrorTracker {
  constructor() {
    this.errors = [];
  }
  
  track(error, context = {}) {
    const errorLog = {
      timestamp: new Date().toISOString(),
      message: error.message,
      status: error.status,
      context,
      stack: error.stack
    };
    
    this.errors.push(errorLog);
    
    // Send to monitoring service
    this.sendToMonitoring(errorLog);
  }
  
  sendToMonitoring(errorLog) {
    // Send to your error tracking service
    // Example: Sentry, LogRocket, etc.
    console.error('Error tracked:', errorLog);
  }
  
  getRecentErrors(limit = 10) {
    return this.errors.slice(-limit);
  }
}

// Usage
const tracker = new ErrorTracker();

try {
  await createToken(data);
} catch (error) {
  tracker.track(error, {
    operation: 'createToken',
    tokenData: data
  });
}

---

Best Practices

1. Always Handle Errors

javascript

// ❌ Bad: Unhandled errors
const token = await fetch(url).then(r => r.json());

// ✅ Good: Proper error handling
try {
  const response = await fetch(url);
  if (!response.ok) throw new Error('Request failed');
  const token = await response.json();
} catch (error) {
  console.error('Error:', error);
  // Handle error appropriately
}

2. Provide User-Friendly Messages

javascript

function getUserFriendlyError(error) {
  const messages = {
    401: 'Please sign in again',
    403: 'You don\'t have permission for this action',
    404: 'Token not found',
    429: 'Too many requests. Please wait a moment',
    500: 'Something went wrong. Please try again'
  };
  
  return messages[error.status] || 'An error occurred';
}

// Usage
catch (error) {
  const userMessage = getUserFriendlyError(error);
  showNotification(userMessage);
}

3. Log for Debugging

javascript

catch (error) {
  // Log full details for debugging
  console.error('API Error:', {
    status: error.status,
    message: error.message,
    details: error.details,
    url: error.url,
    timestamp: new Date().toISOString()
  });
  
  // Show simple message to user
  showError('Something went wrong');
}

4. Fail Gracefully

javascript

async function loadTokens() {
  try {
    const tokens = await fetch('https://api.vision.meme/tokens/me');
    return tokens;
  } catch (error) {
    console.error('Failed to load tokens:', error);
    // Return empty array instead of crashing
    return [];
  }
}

---

Testing Error Scenarios

javascript

// Mock error responses for testing
async function mockErrorResponse(status, error) {
  return {
    ok: false,
    status,
    json: async () => ({ error })
  };
}

// Test 401 error
const response = await mockErrorResponse(401, 'Unauthorized');
// ... handle error

// Test 429 error
const response = await mockErrorResponse(429, 'Rate limit exceeded');
// ... handle error

---

Next Steps

• Rate Limits - Understand rate limiting

• Code Examples - See error handling in practice

• Token Endpoints - Learn about token operations

---

Need Help?

• 💬 Discord Community

• 📱 Telegram Support

• 📧 Email Support

---

© 2025 Vision.meme. All rights reserved.