Error Handling

The API uses standard HTTP response codes and consistent error formats to help you handle issues gracefully.

HTTP Status Codes

Status Code	Meaning	Description
200	OK	Request successful
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API token
403	Forbidden	Access denied (account inactive/suspended)
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Error Response Format

All errors follow a consistent JSON structure:

{
  "error": "Error message describing what went wrong",
  "code": "ERROR_CODE",
  "details": {
    // Additional context when available
  }
}

Common Error Scenarios

Authentication Errors

Missing Token

{
  "error": "Authentication required"
}

Invalid Token

{
  "error": "Invalid authentication token"
}

Account Status Errors

Account Suspended

{
  "error": "Account is not active. Please contact support.",
  "code": "ACCOUNT_SUSPENDED"
}

Order Creation Errors

Credit Limit Exceeded

{
  "error": "You have reached your credit limit. For assistance, please reach out to our support team.",
  "code": "CREDIT_LIMIT_EXCEEDED"
}

Product Not Available

{
  "error": "Product not found or not available: 507f1f77bcf86cd799439011",
  "code": "PRODUCT_NOT_AVAILABLE"
}

Insufficient Stock

{
  "error": "Some products are not available",
  "code": "INSUFFICIENT_STOCK",
  "unavailableItems": [
    {
      "productId": "507f1f77bcf86cd799439011",
      "productName": "Microsoft Office 2021",
      "requestedQuantity": 10,
      "availableQuantity": 5
    }
  ]
}

Validation Errors

Missing Required Fields

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "products": "Products array is required"
  }
}

Invalid Product Format

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "products[0].amount": "Amount must be a positive number"
  }
}

Error Handling Best Practices

1. Check Status Code First

const response = await fetch('https://api.attivita.de/api/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(orderData)
});

if (!response.ok) {
  const error = await response.json();
  
  switch (response.status) {
    case 400:
      // Handle validation errors
      console.error('Validation error:', error);
      break;
    case 401:
      // Handle authentication errors
      console.error('Authentication failed');
      break;
    case 403:
      // Handle authorization errors
      console.error('Access denied:', error.error);
      break;
    case 429:
      // Handle rate limiting
      console.error('Too many requests');
      break;
    default:
      // Handle other errors
      console.error('Request failed:', error);
  }
  return;
}

const order = await response.json();

2. Implement Retry Logic

async function apiRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        // Rate limited - wait before retry
        const retryAfter = response.headers.get('Retry-After') || 60;
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      
      if (response.status >= 500) {
        // Server error - exponential backoff
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
        continue;
      }
      
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
}

3. Log Errors for Debugging

function logApiError(endpoint, status, error) {
  console.error({
    timestamp: new Date().toISOString(),
    endpoint,
    status,
    error: error.error || 'Unknown error',
    code: error.code,
    details: error.details
  });
}

Error Recovery Strategies

Credit Limit Issues

1. Check your current credit status
2. Contact support to increase limit
3. Consider splitting large orders

Stock Availability

1. Check product availability first
2. Reduce order quantity
3. Set up webhooks for stock notifications

Authentication Failures

1. Verify token is correct
2. Check token hasn't expired
3. Ensure proper header format

Testing Error Scenarios

Use sandbox mode to test error handling:

# Test with invalid product ID
curl -X POST https://api.attivita.de/api/orders \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Sandbox-Mode: true" \
  -d '{"products": [{"productId": "invalid", "amount": 1}]}'

# Test with excessive quantity
curl -X POST https://api.attivita.de/api/orders \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Sandbox-Mode: true" \
  -d '{"products": [{"productId": "valid-id", "amount": 9999}]}'

Support

If you encounter persistent errors:

1. Check the API Status Page
2. Review your implementation against documentation
3. Contact support with:
   • Error message and code
   • Request details (endpoint, headers, body)
   • Timestamp of occurrence
   • Your customer ID

Next Steps

• Implement proper Rate Limiting handling
• Set up Webhooks for notifications
• Read Best Practices