Error Handling

Common errors and how to handle them gracefully in your TinyRebrand API integration

Proper error handling is crucial for building robust applications. TinyRebrand's API provides detailed error information to help you understand and resolve issues quickly.

Error Response Structure

All error responses follow a consistent format:

{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "Human-readable error message",
  "meta": {
    "errors": [
      {"name": "field", "error": "Specific validation error"}
    ]
  }
}

Common Error Types

400 Bad Request: Invalid request format, missing required fields, or invalid data values.

401 Unauthorized: Missing, invalid, or expired access token.

403 Forbidden: Insufficient permissions or scope for the requested action.

404 Not Found: Requested resource doesn't exist or has been deleted.

429 Too Many Requests: Rate limit exceeded. Check rate limit headers for retry information.

Specific Error Examples

Validation Errors

{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "meta": {
    "errors": [
      {"name": "title", "error": "The title field is required"},
      {"name": "url", "error": "The url must be a valid URL"},
      {"name": "slug", "error": "The slug must be unique"}
    ]
  }
}

Authentication Errors

{
  "status": 401,
  "code": "INVALID_OR_EXPIRED_TOKEN",
  "message": "Invalid or expired token",
  "meta": {
    "message": "Invalid or expired token"
  }
}

Permission Errors

{
  "status": 403,
  "code": "INSUFFICIENT_PERMISSIONS",
  "message": "Insufficient permissions",
  "meta": {
    "message": "Insufficient permissions"
  }
}

Rate Limit Errors

{
  "status": 429,
  "code": "RATE_LIMIT_ERROR",
  "message": "Too many requests from this IP, please try again later.",
  "meta": {
    "message": "Too many requests from this IP, please try again later."
  }
}

Error Codes Reference

Error Code	HTTP Status	Description
VALIDATION_ERROR	400	One or more fields failed validation
INVALID_OR_EXPIRED_TOKEN	401	Access token is invalid or expired
INSUFFICIENT_PERMISSIONS	403	Token lacks required permissions
NOT_FOUND	404	Requested resource doesn't exist
RATE_LIMIT_ERROR	429	Too many requests in time window
ERROR	500	Internal server error

Error Handling Best Practices

1. Check the Response Status

async function makeApiCall(url, options) {
  try {
    const response = await fetch(url, options);
    const data = await response.json();
    
    if (data.status >= 400 || data.code !== 'OK') {
      throw new ApiError(data.message, data.code, data.meta);
    }
    
    return { data: data.data, meta: data.meta };
  } catch (error) {
    console.error('API call failed:', error);
    throw error;
  }
}

2. Handle Specific Error Types

function handleApiError(error) {
  switch (error.code) {
    case 'VALIDATION_ERROR':
      // Show validation errors to user
      showValidationErrors(error.meta?.errors || []);
      break;
      
    case 'INVALID_OR_EXPIRED_TOKEN':
      // Redirect to login or refresh token
      redirectToLogin();
      break;
      
    case 'INSUFFICIENT_PERMISSIONS':
      // Show permission denied message
      showPermissionError();
      break;
      
    case 'RATE_LIMIT_ERROR':
      // Implement retry with backoff
      scheduleRetry();
      break;
      
    default:
      // Generic error handling
      showGenericError(error.message);
  }
}

3. Implement Retry Logic

class ApiClient {
  async makeRequest(url, options, retries = 3) {
    for (let i = 0; i <= retries; i++) {
      try {
        const response = await fetch(url, options);
        const data = await response.json();
        
        if (data.status >= 400 || data.code !== 'OK') {
          // Handle specific errors
          if (data.code === 'RATE_LIMIT_ERROR' && i < retries) {
            const delay = Math.pow(2, i) * 1000;
            await this.sleep(delay);
            continue;
          }
          
          throw new ApiError(data.message, data.code, data.meta);
        }
        
        return data.data;
      } catch (error) {
        if (i === retries) throw error;
        
        // Exponential backoff for network errors
        await this.sleep(Math.pow(2, i) * 1000);
      }
    }
  }
  
  sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

4. Create a Custom Error Class

class ApiError extends Error {
  constructor(message, code, meta) {
    super(message);
    this.name = 'ApiError';
    this.code = code;
    this.meta = meta;
  }
  
  isValidationError() {
    return this.code === 'VALIDATION_ERROR';
  }
  
  isAuthError() {
    return this.code === 'INVALID_OR_EXPIRED_TOKEN' || this.code === 'INSUFFICIENT_PERMISSIONS';
  }
  
  isRateLimitError() {
    return this.code === 'RATE_LIMIT_ERROR';
  }
}

User-Friendly Error Messages

Always provide clear, actionable error messages to your users:

function getUserFriendlyMessage(error) {
  const messages = {
    'VALIDATION_ERROR': 'Please check your input and try again.',
    'INVALID_OR_EXPIRED_TOKEN': 'Your session has expired. Please log in again.',
    'INSUFFICIENT_PERMISSIONS': 'You don't have permission to perform this action.',
    'RATE_LIMIT_ERROR': 'You're making requests too quickly. Please wait a moment.',
    'NOT_FOUND': 'The requested item could not be found.',
    'ERROR': 'Something went wrong on our end. Please try again later.'
  };
  
  return messages[error.code] || 'An unexpected error occurred.';
}

Debugging Tips

Log Full Error Details: Include the complete error response in your logs for debugging.

Use Request IDs: Include request IDs in your error reports for faster support resolution.

Getting Help

If you encounter persistent issues, please reach out to us if you experience:

Persistent 500 server errors
Unexpected 404 errors for resources that should exist
Rate limits that seem incorrect
Error messages that don't match the documentation

API Structure

API Reference