API Error Handling
The Mahalo Health API uses standard HTTP status codes and consistent error response formats to help you handle errors in your applications.
Error Response Format
All API errors follow a consistent JSON format:
{
"error": {
"code": "ERROR_CODE",
"message": "A human-readable error message",
"details": {
// Additional error details (optional)
}
}
}Common Error Codes
The following error codes are used across all API endpoints:
| Code | HTTP Status | Description |
|---|---|---|
| UNAUTHORIZED | 401 | Authentication credentials were missing or invalid |
| FORBIDDEN | 403 | The authenticated user does not have access to the requested resource |
| NOT_FOUND | 404 | The requested resource was not found |
| VALIDATION_ERROR | 422 | The request payload contains invalid data |
| RATE_LIMIT_EXCEEDED | 429 | You have exceeded the allowed number of requests |
| INTERNAL_SERVER_ERROR | 500 | An unexpected error occurred on the server |
Validation Errors
When a request contains invalid data, the API returns a 422 Unprocessable Entity status code with details about the validation errors:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "The request payload contains invalid data",
"details": {
"fields": {
"email": "Invalid email format",
"program_id": "Program ID is required"
}
}
}
}Important
Always check for error responses in your API integrations and handle them appropriately. Do not assume that API calls will always succeed.
Error Handling Best Practices
- Always check the HTTP status code of API responses
- Parse the error response body to get detailed error information
- Implement retry logic for transient errors (e.g., 429 Too Many Requests, 503 Service Unavailable)
- Log detailed error information for debugging
- Display user-friendly error messages to end users
Example Error Handling
try {
const response = await fetch('https://api.mahalo.health/v1/app/dashboard', {
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
}
});
if (!response.ok) {
const errorData = await response.json();
throw new Error(`API Error: ${errorData.error.code} - ${errorData.error.message}`);
}
const data = await response.json();
// Process successful response
} catch (error) {
console.error('Error fetching dashboard data:', error);
// Handle error appropriately
}