Error Handling

Learn how to handle errors and implement robust error handling in your applications

Error Response Format

All errors from the SNS Auctions API follow a consistent JSON format:

{
  "error": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": {
    "field": "fieldName",
    "reason": "Additional context"
  }
}

Common Error Codes

UNAUTHORIZED

HTTP 401

Missing or invalid API key. Ensure your Authorization header is correct.

INVALID_REQUEST

HTTP 400

Invalid request parameters. Check the error details for which field is invalid.

NOT_FOUND

HTTP 404

Resource not found. The auction, user, or API key you're looking for doesn't exist.

RATE_LIMITED

HTTP 429

Rate limit exceeded. See the Rate Limiting guide for handling this error.

INTERNAL_ERROR

HTTP 500

Internal server error. This is rare and usually temporary. Retry with exponential backoff.

Example Errors

// Invalid authentication
{
  "error": "UNAUTHORIZED",
  "message": "Authentication failed",
  "details": {
    "reason": "Invalid API key format"
  }
}

// Invalid request
{
  "error": "INVALID_REQUEST",
  "message": "Invalid domain name: not-a-valid-sns-domain",
  "details": {
    "field": "domainNames[0]",
    "reason": "SNS domain names must be 3-63 characters"
  }
}

// Resource not found
{
  "error": "NOT_FOUND",
  "message": "Auction not found",
  "details": {
    "auctionId": "invalid-id"
  }
}

Error Handling Best Practices

1. Always Check HTTP Status

Don't rely solely on response parsing. Check the HTTP status code first. A 4xx or 5xx response indicates an error.

2. Handle Different Error Types

Implement specific error handling for authentication errors (401), rate limits (429), and server errors (5xx).

3. Parse Error Details

Use the details field to understand what went wrong and display helpful messages to users.

4. Log Errors

Log all API errors with context. Include the request URL, parameters, and error response for debugging.

5. Implement Retry Logic

Retry transient errors (5xx, 429) with exponential backoff. Don't retry authentication errors (401).

Example: Error Handler

async function handleApiRequest(url, options = {}) {
  try {
    const response = await fetch(url, options);

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

      switch (response.status) {
        case 401:
          // Authentication error - don't retry
          console.error('Invalid API key:', error.message);
          throw new AuthenticationError(error.message);

        case 429:
          // Rate limited - implement backoff
          const retryAfter = parseInt(
            response.headers.get('Retry-After') || '60'
          );
          console.warn(`Rate limited. Retry after ${retryAfter}s`);
          throw new RateLimitError(error.message, retryAfter);

        case 400:
          // Invalid request
          console.error('Invalid request:', error.details);
          throw new ValidationError(error.message, error.details);

        case 500:
          // Server error - retry
          console.error('Server error:', error.message);
          throw new ServerError(error.message);

        default:
          throw new Error(error.message || 'Unknown error');
      }
    }

    return await response.json();
  } catch (error) {
    // Log and re-throw
    console.error('API request failed:', {
      url,
      error: error.message,
      timestamp: new Date().toISOString(),
    });
    throw error;
  }
}

Rate Limiting

JavaScript/Node.js

Follow Notify Join Discord