Error Handling
Comprehensive guide to API error codes and handling
Reading time: 4 minutes
Error Handling
Complete reference for API error codes and how to handle them effectively.
Error Response Format
All API errors follow a consistent format:
Error Response Formatjson
{
"error": "error_code",
"message": "Human-readable error message",
"details": {
"field": "additional_error_details"
},
"request_id": "req_abc123xyz"
}HTTP Status Codes
| Code | Meaning | Description |
|---|---|---|
| 200 | OK | Request successful |
| 400 | Bad Request | Invalid request parameters |
| 401 | Unauthorized | Authentication failed |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource not found |
| 409 | Conflict | Resource conflict |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Server error |
| 503 | Service Unavailable | Service temporarily unavailable |
Error Codes Reference
Authentication Errors
authentication_failed
Status: 401
Cause: Invalid authentication credentials or signature
Solution: Verify your HMAC signature and authentication headers
Authentication Errorjson
{
"error": "authentication_failed",
"message": "Invalid HMAC signature",
"request_id": "req_abc123xyz"
}missing_headers
Status: 400
Cause: Required authentication headers are missing
Solution: Include all required headers (X-Awal-Signature-256, X-Timestamp, X-Domain, X-Client-ID)
Validation Errors
validation_failed
Status: 400
Cause: Request data validation failed
Solution: Check the details field for specific validation errors
Validation Errorjson
{
"error": "validation_failed",
"message": "Validation failed",
"details": {
"phone": "Invalid phone number format",
"body": "Message body is required"
},
"request_id": "req_abc123xyz"
}invalid_phone_number
Status: 400
Cause: Phone number format is invalid
Solution: Use international format without + (e.g., 96650000000)
Resource Errors
resource_not_found
Status: 404
Cause: Requested resource doesn't exist
Solution: Verify the resource ID and your permissions
Resource Not Foundjson
{
"error": "resource_not_found",
"message": "Contact not found",
"request_id": "req_abc123xyz"
}resource_conflict
Status: 409
Cause: Resource already exists or conflict detected
Solution: Check if resource already exists or resolve the conflict
Rate Limiting Errors
rate_limit_exceeded
Status: 429
Cause: Rate limit exceeded for the endpoint
Solution: Implement exponential backoff and retry after the specified time
Rate Limit Errorjson
{
"error": "rate_limit_exceeded",
"message": "Rate limit exceeded",
"retry_after": 3600,
"request_id": "req_abc123xyz"
}Server Errors
internal_server_error
Status: 500
Cause: Internal server error
Solution: Retry the request. If it persists, contact support with the request_id
service_unavailable
Status: 503
Cause: Service temporarily unavailable
Solution: Retry after a short delay. Check status page for updates
Error Handling Best Practices
1. Always Check Response Status
Check Response Statusjavascript
async function makeRequest(url, options) {
const response = await fetch(url, options);
if (!response.ok) {
const error = await response.json();
throw new APIError(error.message, error.error, response.status);
}
return await response.json();
}2. Handle Specific Error Codes
Handle Specific Errorsjavascript
try {
const result = await sendMessage(data);
} catch (error) {
switch (error.code) {
case 'authentication_failed':
// Re-authenticate
await refreshCredentials();
break;
case 'rate_limit_exceeded':
// Wait and retry
await wait(error.retry_after);
break;
case 'validation_failed':
// Fix validation errors
console.error('Validation errors:', error.details);
break;
default:
// Log and handle unknown errors
console.error('Unknown error:', error);
}
}3. Retry Logic
Retry Logicjavascript
async function makeRequestWithRetry(url, options, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
const response = await fetch(url, options);
if (response.status === 429) {
const error = await response.json();
const waitTime = error.retry_after || Math.pow(2, attempt) * 1000;
await new Promise(resolve => setTimeout(resolve, waitTime));
continue;
}
if (response.status >= 500) {
// Retry on server errors
if (attempt < maxRetries - 1) {
await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
continue;
}
}
if (!response.ok) {
throw new Error(`Request failed: ${response.status}`);
}
return await response.json();
} catch (error) {
if (attempt === maxRetries - 1) throw error;
await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
}
}
}4. Log Errors with Request ID
Error Loggingjavascript
try {
const result = await makeRequest(url, options);
} catch (error) {
// Always log request_id for support
console.error('API Error:', {
error: error.message,
code: error.code,
request_id: error.request_id,
timestamp: new Date().toISOString()
});
// Send to error tracking service
trackError(error);
}Common Error Scenarios
Invalid Phone Number
Phone Number Formatjson
// ā Wrong
{
"phone": "+96650000000" // Includes +
}
// ā
Correct
{
"phone": "96650000000" // International format without +
}Missing Required Fields
Required Fieldsjson
// ā Wrong
{
"phone": "96650000000"
// Missing 'body' field
}
// ā
Correct
{
"phone": "96650000000",
"body": "Message text"
}Invalid Signature
Signature Issuesjavascript
// Common causes:
// 1. Wrong client secret
// 2. Incorrect timestamp
// 3. Body not properly serialized
// 4. Signature algorithm mismatch
// Solution: Verify signature generation
const signature = generateHMACSignature(timestamp, body);
console.log('Generated signature:', signature);Troubleshooting Guide
Issue: 401 Unauthorized
Checklist:
- Verify client ID and secret are correct
- Check HMAC signature generation
- Ensure timestamp is current (within 5 minutes)
- Verify all required headers are present
Issue: 400 Bad Request
Checklist:
- Review request body format
- Check required fields are present
- Validate data types (strings, numbers, etc.)
- Check phone number format
Issue: 429 Rate Limit
Checklist:
- Check rate limit headers in response
- Implement exponential backoff
- Consider upgrading your plan
- Use webhooks instead of polling
Issue: 500 Server Error
Checklist:
- Retry the request
- Check status page for outages
- If persistent, contact support with request_id
- Verify request format is correct
Error Monitoring
Track Errors
Error Trackingjavascript
class APIErrorTracker {
trackError(error, context) {
const errorData = {
error_code: error.error,
message: error.message,
request_id: error.request_id,
status_code: error.status,
context: context,
timestamp: new Date().toISOString()
};
// Send to monitoring service
this.sendToMonitoring(errorData);
// Log locally
console.error('API Error:', errorData);
}
sendToMonitoring(data) {
// Integrate with your error tracking service
// e.g., Sentry, LogRocket, etc.
}
}Related Sections
Technical Support
Need help with errors?
- š§ Email: support@awalchat.com
- š¬ Live Chat: Available in the dashboard
- š± WhatsApp: Contact us directly via WhatsApp
- š Status Page: Check API Status