The DHMAD API uses standard HTTP status codes and returns detailed error messages to help you debug issues.
All error responses follow this format:
{
"error": "Error Type",
"message": "Human-readable error description",
"details": {
"field": "Additional error details (optional)"
}
}
HTTP Status Codes
201 Created
Resource created successfully
400 Bad Request
Invalid request parameters
401 Unauthorized
Missing or invalid API key
403 Forbidden
API key lacks required permissions
404 Not Found
Resource not found
429 Too Many Requests
Rate limit exceeded
500 Internal Server Error
Server error occurred
Common Errors
401 Unauthorized
Missing API Key
{
"error": "Unauthorized",
"message": "Missing API key. Please include X-API-Key header."
}
{
"error": "Unauthorized",
"message": "Invalid or expired API key"
}
400 Bad Request
Invalid Parameters
{
"error": "Bad Request",
"message": "Invalid request parameters",
"details": {
"amount": "Amount must be a positive number"
}
}
403 Forbidden
Account Not Associated
{
"error": "Forbidden",
"message": "Developer account must be associated with a user account to use this endpoint"
}
404 Not Found
Resource Not Found
{
"error": "Not Found",
"message": "Escrow not found"
}
429 Too Many Requests
Rate Limit Exceeded
{
"error": "Too Many Requests",
"message": "Rate limit exceeded. Please try again later.",
"retryAfter": 3600
}
Error Handling Best Practices
Check Status Codes
Always check the HTTP status code before processing responses
Read Error Messages
Error messages provide specific information about what went wrong
Handle Retries
Implement exponential backoff for 429 and 500 errors
Log Errors
Log error responses for debugging and monitoring
Example Error Handling
async function createEscrow(data) {
try {
const response = await fetch('https://dhmad.tn/api/v1/escrows', {
method: 'POST',
headers: {
'X-API-Key': API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify(data)
});
if (!response.ok) {
const error = await response.json();
switch (response.status) {
case 401:
console.error('Authentication failed:', error.message);
// Handle invalid API key
break;
case 400:
console.error('Invalid request:', error.message);
// Handle validation errors
break;
case 429:
console.error('Rate limit exceeded:', error.message);
// Implement retry logic
break;
default:
console.error('Unexpected error:', error.message);
}
throw new Error(error.message);
}
return await response.json();
} catch (error) {
console.error('Request failed:', error);
throw error;
}
}
Getting Help
If you encounter an error you can’t resolve:
- Check the API Reference for endpoint details
- Review the error message for specific guidance
- Contact support@dhmad.tn with:
- Error message
- Request details (without sensitive data)
- API key ID (not the key itself)
Never log or expose your API keys in error messages or logs. Always redact sensitive information.