AlkantarClanX12
Your IP : 216.73.217.24
# API Error Codes Reference
This document describes the standardized error codes returned by the Leadbox API Client.
## Response Structure
All API methods now return a standardized response structure:
```php
array(
'success' => bool, // Whether the operation succeeded
'data' => mixed, // Response data (null on error, array/object on success)
'count' => int, // Number of items in data array (0 if not array)
'message' => string, // User-friendly message (null if no message)
'error_code' => string, // Machine-readable error code (null on success)
'timestamp' => int // Unix timestamp of response
)
```
## Success Response Examples
### Successful Search with Results
```php
array(
'success' => true,
'data' => [...vehicles...],
'count' => 42,
'message' => null,
'error_code' => null,
'timestamp' => 1234567890
)
```
### Successful Search with No Results
```php
array(
'success' => true,
'data' => array(),
'count' => 0,
'message' => 'No vehicles match your search criteria',
'error_code' => null,
'timestamp' => 1234567890
)
```
## Error Codes
### Connection Errors
#### API_CONNECTION_FAILED
- **Meaning**: Cannot connect to API server
- **User Message**: "Unable to connect to vehicle database. Please try again later."
- **User Action**: Try again later, check internet connection
- **Developer Action**:
- Check API endpoint URL
- Verify network connectivity
- Check firewall rules
- Review error logs for specific connection error message
#### USING_STALE_CACHE
- **Meaning**: API is unavailable but cached data is being returned
- **User Message**: "Showing cached results. Live data temporarily unavailable."
- **User Action**: Results may be outdated, try refreshing later
- **Developer Action**:
- Investigate API downtime
- Check API health monitoring
- Verify API server status
### HTTP Errors
#### API_HTTP_ERROR_XXX
- **Format**: API_HTTP_ERROR_404, API_HTTP_ERROR_500, etc.
- **Meaning**: HTTP error status returned by API
- **User Message**: "Vehicle database returned an error. Please try again later."
- **User Action**: Contact support if error persists
- **Developer Action**:
- Check API endpoint configuration
- Review API authentication credentials
- Verify API request parameters
- Check API server logs
Common HTTP error codes:
- **API_HTTP_ERROR_401**: Unauthorized - Invalid API key
- **API_HTTP_ERROR_403**: Forbidden - API key lacks permissions
- **API_HTTP_ERROR_404**: Not Found - Endpoint doesn't exist
- **API_HTTP_ERROR_429**: Too Many Requests - Rate limit exceeded
- **API_HTTP_ERROR_500**: Internal Server Error - API server problem
- **API_HTTP_ERROR_503**: Service Unavailable - API temporarily down
### Data Errors
#### API_PARSE_ERROR
- **Meaning**: Invalid JSON response from API
- **User Message**: "Received invalid data from vehicle database."
- **User Action**: Contact support
- **Developer Action**:
- Check API response format
- Verify API version compatibility
- Review API server logs
- Check for partial/corrupted response
#### API_INVALID_RESPONSE
- **Meaning**: Unexpected data format in API response
- **User Message**: "Received unexpected data format from vehicle database."
- **User Action**: Contact support
- **Developer Action**:
- Verify API contract/schema
- Check for API version changes
- Review response structure
- Validate expected fields are present
### Lead Submission Errors
#### LEAD_SUBMISSION_FAILED
- **Meaning**: Failed to submit lead to backend
- **User Message**: "Unable to submit lead. Please try again later."
- **User Action**: Try submitting form again
- **Developer Action**:
- Check POSTAsync error logs
- Verify lead data format
- Check API endpoint availability
- Review timeout settings
## Usage Examples
### Checking for Errors in Vehicle Search
```php
$api = LB_API_Client::getInstance();
$params = new SearchParameters();
$params->setMake('Toyota');
$response = $api->VehicleSearch($params);
if (!$response['success']) {
// Handle error
error_log('Vehicle search failed: ' . $response['error_code']);
echo '<div class="error">' . esc_html($response['message']) . '</div>';
return;
}
// Check for empty results
if ($response['count'] === 0) {
echo '<div class="info">' . esc_html($response['message']) . '</div>';
return;
}
// Process vehicles
foreach ($response['data'] as $vehicle) {
// Render vehicle...
}
```
### Checking for Errors in Lead Submission
```php
$api = LB_API_Client::getInstance();
$lead = new LB_Lead_Dto();
$lead->FromArray($form_data);
$response = $api->CreateLead($lead);
if (!$response['success']) {
// Log error with code for monitoring
leadbox_logger()->error('Lead submission failed', array(
'error_code' => $response['error_code'],
'message' => $response['message']
));
// Show user-friendly message
echo '<div class="error">' . esc_html($response['message']) . '</div>';
return;
}
// Success
echo '<div class="success">Thank you! Your submission has been received.</div>';
```
### Using Stale Cache Fallback
```php
$response = $api->VehicleSearch($params);
if (!$response['success']) {
// Check if we're using stale cache
if ($response['error_code'] === 'USING_STALE_CACHE') {
// Still have data to show, but warn user
echo '<div class="warning">' . esc_html($response['message']) . '</div>';
// Continue to render vehicles from cached data
$vehicles = $response['data'];
} else {
// Complete failure, no data available
echo '<div class="error">' . esc_html($response['message']) . '</div>';
return;
}
}
```
## Monitoring and Alerting
You can set up monitoring based on error codes:
```php
// Track API errors for monitoring
function track_api_error($error_code) {
$error_counts = get_transient('leadbox_api_errors') ?: array();
if (!isset($error_counts[$error_code])) {
$error_counts[$error_code] = 0;
}
$error_counts[$error_code]++;
// Alert if too many errors
if ($error_counts[$error_code] > 10) {
// Send alert to monitoring service
alert_admin('High API error rate: ' . $error_code);
}
set_transient('leadbox_api_errors', $error_counts, HOUR_IN_SECONDS);
}
```
## Backward Compatibility
The API client maintains backward compatibility:
- The `GET()`, `POST()`, and `DELETE()` private methods return structured responses on errors
- On success, `GET()` returns raw API data (not wrapped) for backward compatibility
- Public methods like `VehicleSearch()`, `VehicleDetail()`, etc. wrap all responses in the structured format
- Old code checking for `NULL` returns will still work, but should be updated to check `$response['success']`
## Migration Guide
### Before (Old Code)
```php
$vehicles = $api->VehicleSearch($params);
if (!$vehicles) {
echo 'No results found'; // Can't tell if error or empty results!
return;
}
foreach ($vehicles as $vehicle) {
// Render...
}
```
### After (New Code)
```php
$response = $api->VehicleSearch($params);
if (!$response['success']) {
echo '<div class="error">' . esc_html($response['message']) . '</div>';
return;
}
if ($response['count'] === 0) {
echo '<div class="info">' . esc_html($response['message']) . '</div>';
return;
}
foreach ($response['data'] as $vehicle) {
// Render...
}
```
## Benefits
1. **Better User Experience**: Users see meaningful error messages instead of generic "No results"
2. **Easier Debugging**: Developers can quickly identify issues with error codes
3. **Monitoring**: Error codes enable automated monitoring and alerting
4. **Graceful Degradation**: Stale cache fallback prevents complete failures
5. **Consistent Handling**: All API methods follow the same response structure
## Related Files
- `/classes/api.php` - API Client implementation
- `/integrations/ninja-forms/actions/send-lead.php` - Lead submission handling
- `/docs/ERROR_HANDLING_LOGGING.md` - General error handling documentation
---
**Last Updated**: 2025-12-15
**Version**: 1.0.0