Error Handling Guide

This guide covers error handling patterns, common errors, and troubleshooting for LogiDAV APIs.

Standard Error Response Format

All API endpoints return consistent error responses:

{
  "success": false,
  "error": "Error type",
  "message": "Detailed error message"
}

---

HTTP Status Codes

2xx Success

• 200 OK: Request successful, data returned
• 201 Created: Resource created successfully

4xx Client Errors

• 400 Bad Request: Invalid parameters or request format
• 401 Unauthorized: Authentication failed or missing
• 404 Not Found: Resource not found
• 422 Unprocessable Entity: Validation failed

5xx Server Errors

• 500 Internal Server Error: Unexpected server error
• 503 Service Unavailable: Service temporarily unavailable

---

Common Errors

Authentication Errors

Missing Authorization Header

{
  "error": "Unauthorized",
  "message": "Missing Authorization header"
}

HTTP Status: 401

Solution: Add Authorization: Bearer {token} header to request

Example:

# Wrong - missing header
curl https://api.menzzo.fr/api/sale/12345

# Correct
curl -H "Authorization: Bearer {token}" \
  https://api.menzzo.fr/api/sale/12345

---

Invalid or Expired Token

{
  "error": "Unauthorized",
  "message": "Invalid or expired Bearer token"
}

HTTP Status: 401

Solutions: 1. Verify token is correct (no extra spaces or characters) 2. Request new token if expired 3. Check token type matches endpoint (Bearer vs X-API-Token)

---

Chatbot API - Missing X-API-Token

{
  "success": false,
  "error": "Non autorisé",
  "message": "Token d'API manquant ou invalide"
}

HTTP Status: 401

Solution: Use X-API-Token header for Chatbot API endpoints

Example:

# Wrong - using Bearer token
curl -H "Authorization: Bearer {token}" \
  https://api.menzzo.fr/api/sale/details/15000012345

# Correct - using X-API-Token
curl -H "X-API-Token: {token}" \
  https://api.menzzo.fr/api/sale/details/15000012345

---

Resource Not Found Errors

Sale Not Found

{
  "success": false,
  "error": "Commande non trouvée",
  "message": "Aucune commande trouvée avec l'increment ID: 15000012345"
}

HTTP Status: 404

Possible Causes: 1. Invalid increment ID 2. Sale doesn't exist in system 3. Sale not in allowed status (for Chatbot API)

Solution: Verify the order ID is correct

---

Product Not Found

{
  "success": false,
  "error": "Product not found",
  "message": "No product found with SKU: INVALID-SKU"
}

HTTP Status: 404

Solution: Check SKU spelling and existence

---

Validation Errors

Missing Required Parameter

{
  "success": false,
  "error": "Invalid parameters",
  "message": "Missing required field: saleProductId"
}

HTTP Status: 400

Solution: Include all required parameters in request

Example:

# Wrong - missing saleProductId
curl -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"data": {"complaint": "damage"}}' \
  https://api.menzzo.fr/api/sale-sav/create-for-sale-product

# Correct
curl -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"saleProductId": [123], "data": {"complaint": "damage"}}' \
  https://api.menzzo.fr/api/sale-sav/create-for-sale-product

---

Invalid Parameter Format

{
  "success": false,
  "error": "Invalid format",
  "message": "Date must be in YYYY-MM-DD format"
}

HTTP Status: 400

Solution: Use correct format for parameters

Common Formats: - Dates: YYYY-MM-DD (e.g., 2026-01-23) - Times: HH:MM (e.g., 14:30) - Phone: International format (e.g., +33612345678)

---

Invalid Email Format

{
  "success": false,
  "error": "Validation error",
  "message": "Invalid email format"
}

HTTP Status: 400

Solution: Provide valid email address

---

Server Errors

Internal Server Error

{
  "success": false,
  "error": "Internal server error",
  "message": "An unexpected error occurred"
}

HTTP Status: 500

Actions: 1. Check API status 2. Retry request after brief delay 3. If persists, contact support with request details

---

Service Unavailable

{
  "success": false,
  "error": "Service unavailable",
  "message": "Service temporarily unavailable"
}

HTTP Status: 503

Actions: 1. Wait 1-2 minutes and retry 2. Check system status page 3. Contact support if prolonged

---

Error Handling Best Practices

1. Always Check Success Field

const response = await fetch(url, options);
const data = await response.json();

if (!data.success) {
  // Handle error
  console.error(`API Error: ${data.error} - ${data.message}`);
  throw new Error(data.message);
}

// Process successful response
return data.data;

2. Implement Retry Logic

async function apiRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      const data = await response.json();

      if (data.success) {
        return data;
      }

      // Don't retry client errors (4xx)
      if (response.status >= 400 && response.status < 500) {
        throw new Error(data.message);
      }

      // Retry server errors (5xx)
      if (attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }

      throw new Error(data.message);

    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }
    }
  }
}

3. Handle Different Error Types

async function handleAPIRequest(url, options) {
  try {
    const response = await fetch(url, options);
    const data = await response.json();

    if (!data.success) {
      switch (response.status) {
        case 401:
          // Authentication error - refresh token
          await refreshToken();
          return handleAPIRequest(url, options); // Retry

        case 404:
          // Resource not found - inform user
          throw new NotFoundError(data.message);

        case 400:
          // Validation error - fix parameters
          throw new ValidationError(data.message);

        case 500:
        case 503:
          // Server error - retry with backoff
          await delay(2000);
          return handleAPIRequest(url, options);

        default:
          throw new APIError(data.message);
      }
    }

    return data;

  } catch (error) {
    // Network error
    if (error instanceof TypeError) {
      throw new NetworkError('Network request failed');
    }
    throw error;
  }
}

4. Log Errors Properly

function logAPIError(error, context) {
  console.error('API Error:', {
    timestamp: new Date().toISOString(),
    error: error.message,
    endpoint: context.endpoint,
    method: context.method,
    status: context.status,
    requestId: context.requestId,
    // Don't log sensitive data like tokens
  });
}

5. User-Friendly Error Messages

function getUserFriendlyMessage(error) {
  const errorMessages = {
    'Invalid or expired Bearer token': 'Your session has expired. Please log in again.',
    'Missing required field: saleProductId': 'Please select at least one product.',
    'Invalid email format': 'Please enter a valid email address.',
    'Service temporarily unavailable': 'The service is temporarily unavailable. Please try again in a few minutes.',
  };

  return errorMessages[error.message] || 'An error occurred. Please try again.';
}

---

Debugging Checklist

When encountering errors:

• Check HTTP status code
• Read full error message
• Verify authentication header format
• Confirm required parameters included
• Validate parameter formats (dates, emails, etc.)
• Check API endpoint URL is correct
• Verify using correct HTTP method (GET/POST)
• Test with cURL to isolate client issues
• Review recent API changes or maintenance
• Check system status page

---

Testing Error Handling

Test Invalid Token

curl -H "Authorization: Bearer INVALID_TOKEN" \
  https://api.menzzo.fr/api/sale/12345

Expected Response:

{
  "error": "Unauthorized",
  "message": "Invalid or expired Bearer token"
}

Test Missing Parameter

curl -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://api.menzzo.fr/api/contact-lead

Expected Response:

{
  "success": false,
  "error": "Validation error",
  "message": "Missing required fields"
}

Test Not Found

curl -H "Authorization: Bearer {token}" \
  https://api.menzzo.fr/api/sale/999999999

Expected Response:

{
  "success": false,
  "error": "Not found",
  "message": "Sale not found"
}

---

Error Response Examples by Endpoint

Core API

Create SAV - Missing Product ID

{
  "success": false,
  "error": "Invalid parameters",
  "message": "Missing required field: saleProductId"
}

Contact Lead - Invalid Email

{
  "success": false,
  "error": "Validation error",
  "message": "Invalid email format"
}

Chatbot API

Sale Details - Not Found

{
  "success": false,
  "error": "Commande non trouvée",
  "message": "Aucune commande trouvée avec l'increment ID: 15000012345"
}

Supplier APIs

Ship Sale - Already Shipped

{
  "success": false,
  "message": "Aucun produit livrable n'a été trouvé pour être expédié"
}

Get Sales - Invalid Date Format

{
  "success": false,
  "error": "Invalid format",
  "message": "date_from must be in YYYY-MM-DD format"
}

---

Getting Help

If you're experiencing persistent errors:

1. Gather Information:
2. Full error message
3. HTTP status code
4. Request details (endpoint, method, parameters)
5. Timestamp

6. Your API token identifier (not the actual token)

7. Contact Support:

8. Email: technique@menzzo.fr
9. Subject: API Error - [Endpoint Name]

10. Include: All information from step 1

11. Expected Response Time:

12. Critical issues: Within 4 hours
13. Normal issues: Within 1 business day

---

Related Documentation

• Authentication Guide - Authentication methods and errors
• Core API - Core API endpoint errors
• Chatbot API - Chatbot API endpoint errors
• Supplier APIs - Supplier API endpoint errors