Error Handling

Overview

The EZMint API uses conventional HTTP response codes and provides detailed error messages to indicate the success or failure of requests. This guide explains how to handle errors and implement robust error handling in your applications.

Error Response Format

All error responses follow a consistent format:

{
  "error": {
    "code": "string",      // Error code
    "message": "string",   // Human-readable error message
    "details": {          // Optional additional error details
      "field": "string",  // Field that caused the error (if applicable)
      "reason": "string"  // Specific reason for the error
    }
  }
}

HTTP Status Codes

2xx - Success

  • • 200 OK - Request succeeded
  • • 201 Created - Resource was successfully created
  • • 204 No Content - Request succeeded with no response body

4xx - Client Errors

  • • 400 Bad Request - Invalid request format or parameters
  • • 401 Unauthorized - Missing or invalid API key
  • • 403 Forbidden - Valid API key but insufficient permissions
  • • 404 Not Found - Resource not found
  • • 409 Conflict - Request conflicts with existing resource
  • • 429 Too Many Requests - Rate limit exceeded

5xx - Server Errors

  • • 500 Internal Server Error - Unexpected server error
  • • 502 Bad Gateway - Invalid response from upstream service
  • • 503 Service Unavailable - Service temporarily unavailable

Common Error Scenarios

Authentication Errors

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key provided",
    "details": {
      "reason": "API key has expired"
    }
  }
}

Validation Errors

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": {
      "field": "name",
      "reason": "Name must be between 3 and 50 characters"
    }
  }
}

Blockchain Errors

{
  "error": {
    "code": "blockchain_error",
    "message": "Failed to mint NFT",
    "details": {
      "reason": "Insufficient SOL balance for transaction"
    }
  }
}

Network-Related Errors

400 Bad Request

{
  "error": "Invalid network. Use 'mainnet' or 'devnet'"
}

Returned when an invalid network parameter is provided.

400 Bad Request

{
  "error": "Collection network does not match requested network"
}

Returned when trying to mint an NFT on a different network than its collection.

Best Practices

1. Check HTTP Status Codes

// JavaScript example
async function mintNFT(data) {
  try {
    const response = await fetch('https://api.ezmint.xyz/api/nfts', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error.message);
    }

    return await response.json();
  } catch (error) {
    console.error('Minting failed:', error);
    throw error;
  }
}

2. Handle Rate Limits

// JavaScript example with exponential backoff
async function mintWithRetry(data, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await mintNFT(data);
    } catch (error) {
      if (error.status === 429) {
        const backoff = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, backoff));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

3. Validate Input Parameters

// JavaScript example
function validateNFTData(data) {
  if (!data.name || data.name.length < 3 || data.name.length > 50) {
    throw new Error('Name must be between 3 and 50 characters');
  }
  
  if (!data.image) {
    throw new Error('Image is required');
  }
  
  // Add more validation as needed
}

See Also