Error Handling
Understanding API errors and how to handle them.
Error Response Format
All errors return a consistent JSON format:
{
"error": "Error message here",
"code": "ERROR_CODE",
"details": { ... } // Optional additional information
}HTTP Status Codes
2xx Success200- Request succeeded201- Resource created204- Request succeeded, no content returned
4xx Client Errors400- Bad request (invalid parameters)401- Unauthorized (missing/invalid API key)403- Forbidden (insufficient permissions)404- Resource not found409- Conflict (idempotency key reused)422- Validation error429- Rate limit exceeded
5xx Server Errors500- Internal server error502- Bad gateway503- Service temporarily unavailable
Common Errors
Invalid From Address
{
"error": "Domain not verified",
"code": "DOMAIN_NOT_VERIFIED"
}The domain in the "from" address isn't verified or not linked to your API key.
Missing Required Field
{
"error": "Validation failed",
"code": "VALIDATION_ERROR",
"details": {
"to": "Required field"
}
}One or more required fields are missing from your request.
Invalid Email Address
{
"error": "Invalid email address",
"code": "INVALID_EMAIL",
"details": {
"field": "to",
"value": "not-an-email"
}
}One of the email addresses in the request is invalid.
Email Limit Exceeded
{
"error": "Monthly email limit exceeded",
"code": "LIMIT_EXCEEDED",
"details": {
"limit": 10000,
"used": 10000
}
}You've reached your plan's monthly email limit.
Account Suspended
{
"error": "Sending suspended due to low reputation score.",
"code": "ACCOUNT_SUSPENDED"
}Your account has been suspended. This can happen automatically when our abuse detection systems identify high-confidence abuse signals, or manually by our team after review. Suspended accounts cannot send emails or use the API. See the Acceptable Use Policy for details. You can submit an appeal from the suspension page in your dashboard.
Abuse Detected
{
"error": "Blocked by abuse detection",
"code": "ABUSE_BLOCKED"
}Your send was blocked by our real-time abuse detection system. This typically indicates one of: unusually high sending velocity, high bounce/failure rate, too many unique recipient domains, or repeated identical content. This is a temporary block — review your sending patterns and try again. Repeated blocks may lead to automatic account suspension.
Content Rejected
{
"error": "Content rejected due to spam detection: ...",
"code": "CONTENT_REJECTED"
}Your email content was flagged by our content scanner. Review the matched keywords in the error message and rephrase your content to avoid common spam triggers.
Handling Errors
async function sendEmail(email) {
const response = await fetch('https://getmailer.co/api/emails', {
method: 'POST',
headers: {
'Authorization': 'Bearer ' + apiKey,
'Content-Type': 'application/json'
},
body: JSON.stringify(email)
});
if (!response.ok) {
const error = await response.json();
switch (response.status) {
case 400:
case 422:
// Validation error - fix the request
console.error('Invalid request:', error.details);
throw new Error(error.error);
case 401:
// Auth error - check API key
throw new Error('Invalid API key');
case 429:
// Rate limited - retry after delay
const retryAfter = error.retryAfter || 60;
await sleep(retryAfter * 1000);
return sendEmail(email); // Retry
case 500:
case 502:
case 503:
// Server error - retry with backoff
await sleep(5000);
return sendEmail(email);
default:
throw new Error(error.error);
}
}
return response.json();
}Abuse Detection Errors
GetMailer uses automated systems to protect our platform. If your sends are being blocked, here's what to check:
ABUSE_BLOCKED
This is a temporary block. Do not retry immediately — back off and review your sending patterns. Common causes: sending too fast, high bounce rates, or repeated identical content. Fix the underlying issue and try again after a few minutes.
ACCOUNT_SUSPENDED
Your account has been suspended. Do not retry — all sends will fail until your account is reinstated. Log in to your dashboard to see the reason and submit an appeal. Only our team can reinstate suspended accounts.
CONTENT_REJECTED
Your email content was flagged. Check the error message for which keywords triggered it, rephrase your content, and retry.