Skip to main content

​
Error Response Format

All API endpoints return consistent error responses with the following structure: 
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "specific_field_name",
      "value": "invalid_value"
    }
  }
}

​
Common Error Codes

​
Authentication Errors

​
Invalid API Key

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

​
Missing API Key

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is required"
  }
}

​
Validation Errors

​
Invalid Plate Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid plate number format",
    "details": {
      "field": "plateNumber",
      "value": "INVALID_PLATE"
    }
  }
}

​
Missing Required Fields

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required field: referenceId",
    "details": {
      "field": "referenceId",
      "value": null
    }
  }
}

​
Resource Not Found Errors

​
Invalid Location ID

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Location not found",
    "details": {
      "field": "locationId",
      "value": "invalid_location_123"
    }
  }
}

​
Location Update Errors

When updating locations, you may encounter specific errors: 
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Location not found or not accessible",
    "details": {
      "field": "locationId",
      "value": "invalid_location_123"
    }
  }
}

​
Invalid Whitelist ID

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Whitelist entry not found",
    "details": {
      "field": "whitelistId",
      "value": "invalid_whitelist_123"
    }
  }
}

​
Duplicate Vehicle Errors

{
  "success": false,
  "error": {
    "code": "DUPLICATE_VEHICLE",
    "message": "Vehicle with this plate already exists in whitelist",
    "details": {
      "plateType": "DXB",
      "plateCode": "White",
      "plateNumber": "12345"
    }
  }
}

​
Rate Limiting Errors

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests"
  }
}

​
Network Errors

​
Connection Timeout

async function makeRequestWithTimeout(url, options, timeout = 10000) {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), timeout);
  
  try {
    const response = await fetch(url, {
      ...options,
      signal: controller.signal
    });
    clearTimeout(timeoutId);
    return response;
  } catch (error) {
    clearTimeout(timeoutId);
    if (error.name === 'AbortError') {
      throw new Error('Request timeout - please check your connection');
    }
    throw error;
  }
}

​
Comprehensive Error Handler

Implement a comprehensive error handler for all scenarios:
class APIErrorHandler {
  static handleError(error, context = {}) {
    const errorInfo = {
      timestamp: new Date().toISOString(),
      context,
      ...this.parseError(error)
    };
    
    // Log error for debugging
    console.error('API Error:', errorInfo);
    
    // Return user-friendly error message
    return {
      success: false,
      error: errorInfo,
      userMessage: this.getUserMessage(errorInfo)
    };
  }
  
  static parseError(error) {
    if (error.response) {
      const { status, data } = error.response;
      return {
        type: 'api_error',
        status,
        code: data?.error?.code || 'UNKNOWN_ERROR',
        message: data?.error?.message || 'API request failed',
        details: data?.error?.details
      };
    } else if (error.request) {
      return {
        type: 'network_error',
        message: 'Unable to connect to API server'
      };
    } else {
      return {
        type: 'client_error',
        message: error.message || 'An unexpected error occurred'
      };
    }
  }
  
  static getUserMessage(errorInfo) {
    switch (errorInfo.code) {
      case 'UNAUTHORIZED':
        return 'Please check your API key and try again.';
      case 'FORBIDDEN':
        return 'You do not have permission to access this resource.';
      case 'NOT_FOUND':
        return 'The requested resource was not found.';
      case 'VALIDATION_ERROR':
        return 'Please check your input data and try again.';
      case 'DUPLICATE_VEHICLE':
        return 'This vehicle is already in the whitelist.';
      case 'RATE_LIMIT_EXCEEDED':
        return 'Too many requests. Please wait a moment and try again.';
      default:
        return 'An error occurred. Please try again later.';
    }
  }
}

// Usage
try {
  const result = await api.addWhitelistVehicle(locationId, vehicleData);
} catch (error) {
  const errorInfo = APIErrorHandler.handleError(error, { 
    operation: 'add_vehicle',
    locationId,
    vehicleData 
  });
  
  // Show user-friendly message
  showNotification(errorInfo.userMessage);
  
  // Log detailed error for debugging
  console.error('Detailed error:', errorInfo);
}

​
Troubleshooting Checklist

1

Check API Key

Verify your API key is correct and has the necessary permissions for the requested resource.
2

Validate Request Data

Ensure all required fields are present and data formats are correct according to the API specification.
3

Check Rate Limits

Verify you haven’t exceeded the 1000 requests per hour limit. Check rate limit headers in responses.
4

Verify Resource IDs

Confirm that location IDs and whitelist IDs are valid and exist in your account.
5

Test Network Connectivity

Ensure your application can reach the API endpoints and there are no firewall or network issues.

​
Getting Help

Contact Support

Get help with specific error scenarios and troubleshooting.

API Status

Check API status and known issues.