Skip to main content

Error Codes Reference

Standard error codes and error handling across the ZÈYA platform.

📋 Standard Error Response Format​

All API errors follow this format:

{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "errors": {
    "field_name": ["Validation error message"]
  }
}

🔢 HTTP Status Codes​

Success Codes​

  • 200 - OK (Success)
  • 201 - Created (Resource created)
  • 204 - No Content (Success, no response body)

Client Error Codes​

  • 400 - Bad Request (Invalid request)
  • 401 - Unauthorized (Authentication required)
  • 403 - Forbidden (Access denied)
  • 404 - Not Found (Resource not found)
  • 422 - Unprocessable Entity (Validation failed)
  • 429 - Too Many Requests (Rate limit exceeded)

Server Error Codes​

  • 500 - Internal Server Error
  • 502 - Bad Gateway
  • 503 - Service Unavailable

🏷️ Error Codes​

Authentication Errors​

CodeHTTP StatusDescription
AUTH_REQUIRED401Authentication required
AUTH_INVALID_TOKEN401Invalid or expired token
AUTH_TOKEN_EXPIRED401Token has expired
AUTH_INVALID_CREDENTIALS401Invalid email/password
AUTH_ACCOUNT_DISABLED403Account is disabled
AUTH_ACCOUNT_LOCKED403Account is locked

Validation Errors​

CodeHTTP StatusDescription
VALIDATION_ERROR422Validation failed
VALIDATION_REQUIRED422Required field missing
VALIDATION_INVALID_FORMAT422Invalid field format
VALIDATION_INVALID_VALUE422Invalid field value

Resource Errors​

CodeHTTP StatusDescription
RESOURCE_NOT_FOUND404Resource not found
RESOURCE_ALREADY_EXISTS409Resource already exists
RESOURCE_CONFLICT409Resource conflict
RESOURCE_UNAVAILABLE503Resource temporarily unavailable

Permission Errors​

CodeHTTP StatusDescription
PERMISSION_DENIED403Permission denied
INSUFFICIENT_PERMISSIONS403Insufficient permissions
UNAUTHORIZED_ACCESS403Unauthorized access attempt

Rate Limiting​

CodeHTTP StatusDescription
RATE_LIMIT_EXCEEDED429Rate limit exceeded
TOO_MANY_REQUESTS429Too many requests

Server Errors​

CodeHTTP StatusDescription
INTERNAL_ERROR500Internal server error
SERVICE_UNAVAILABLE503Service temporarily unavailable
DATABASE_ERROR500Database operation failed
EXTERNAL_SERVICE_ERROR502External service error

🔍 Error Handling Examples​

API (Laravel)​

// Validation error
return response()->json([
    'success' => false,
    'error' => 'Validation failed',
    'code' => 'VALIDATION_ERROR',
    'errors' => $validator->errors()
], 422);

// Not found
return response()->json([
    'success' => false,
    'error' => 'Product not found',
    'code' => 'RESOURCE_NOT_FOUND'
], 404);

// Unauthorized
return response()->json([
    'success' => false,
    'error' => 'Authentication required',
    'code' => 'AUTH_REQUIRED'
], 401);

Mobile App (React Native)​

try {
  const response = await apiCall('endpoint');
} catch (error) {
  if (error.response?.data?.code === 'AUTH_INVALID_TOKEN') {
    // Handle token expiration
    await logout();
    router.push('/login');
  } else if (error.response?.data?.code === 'VALIDATION_ERROR') {
    // Handle validation errors
    const errors = error.response.data.errors;
    // Display validation errors to user
  } else if (error.response?.data?.code === 'RESOURCE_NOT_FOUND') {
    // Handle not found
    Alert.alert('Not Found', error.response.data.error);
  } else {
    // Handle generic error
    Alert.alert('Error', error.response?.data?.error || 'An error occurred');
  }
}

Admin Panel (Next.js)​

try {
  const response = await apiCall('endpoint');
} catch (error) {
  const errorCode = error.response?.data?.code;
  
  switch (errorCode) {
    case 'AUTH_INVALID_TOKEN':
      // Redirect to login
      Cookies.remove('auth_token');
      router.push('/authentication/sign-in');
      break;
      
    case 'VALIDATION_ERROR':
      // Show validation errors
      const errors = error.response.data.errors;
      setValidationErrors(errors);
      break;
      
    case 'RESOURCE_NOT_FOUND':
      // Show not found message
      toast.error('Resource not found');
      break;
      
    default:
      // Show generic error
      toast.error(error.response?.data?.error || 'An error occurred');
  }
}

🛡️ Error Handling Best Practices​

1. Always Handle Errors​

// ✅ Good
try {
  const data = await apiCall('endpoint');
} catch (error) {
  handleError(error);
}

// ❌ Bad
const data = await apiCall('endpoint'); // No error handling

2. Provide User-Friendly Messages​

// ✅ Good
const userMessage = errorCodes[error.code] || 'An error occurred';
showMessage(userMessage);

// ❌ Bad
showMessage(error.message); // Technical error message

3. Log Errors for Debugging​

// ✅ Good
catch (error) {
  console.error('API Error:', error);
  logError(error); // Send to error tracking service
  showUserFriendlyMessage(error);
}

4. Handle Network Errors​

if (error.request) {
  // Network error - no response received
  showMessage('Network error. Please check your connection.');
} else if (error.response) {
  // Server responded with error
  handleServerError(error.response);
} else {
  // Something else happened
  showMessage('An unexpected error occurred.');
}

📱 Client-Side Error Handling​

Mobile App Error Handler​

const errorHandler = (error) => {
  const status = error?.response?.status;
  const code = error?.response?.data?.code;
  
  if (status === 401 || code === 'AUTH_INVALID_TOKEN') {
    // Handle authentication error
    logout();
    router.push('/login');
  } else if (code === 'VALIDATION_ERROR') {
    // Handle validation errors
    const errors = error.response.data.errors;
    showValidationErrors(errors);
  } else {
    // Handle generic error
    Alert.alert('Error', error.response?.data?.error || 'An error occurred');
  }
};

Admin Panel Error Handler​

const handleApiError = (error) => {
  const code = error.response?.data?.code;
  
  const errorMessages = {
    'AUTH_INVALID_TOKEN': 'Your session has expired. Please log in again.',
    'VALIDATION_ERROR': 'Please check your input and try again.',
    'RESOURCE_NOT_FOUND': 'The requested resource was not found.',
    'PERMISSION_DENIED': 'You do not have permission to perform this action.',
  };
  
  const message = errorMessages[code] || error.response?.data?.error || 'An error occurred';
  toast.error(message);
  
  if (code === 'AUTH_INVALID_TOKEN') {
    router.push('/authentication/sign-in');
  }
};

🔄 Retry Logic​

Implementing Retry​

const apiCallWithRetry = async (endpoint, options, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await apiCall(endpoint, options);
    } catch (error) {
      const code = error.response?.data?.code;
      
      // Don't retry on client errors (4xx)
      if (error.response?.status < 500) {
        throw error;
      }
      
      // Retry on server errors (5xx)
      if (i === maxRetries - 1) {
        throw error;
      }
      
      // Wait before retry (exponential backoff)
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
};