Error Codes Reference

SMTP and API error codes with troubleshooting guidance

SMTP Errors

421 4.7.0 Service temporarily unavailable

Server is too busy or temporarily unavailable.

Action: Retry in 5-15 minutes. Implement exponential backoff.

450 4.7.1 Mailbox temporarily unavailable

Recipient mailbox is temporarily unable to receive.

Action: Retry in 30-60 minutes.

451 4.4.5 Server too busy

Too many connections or server load too high.

Action: Retry with reduced connection count. Check your sending rate.

452 4.2.2 Mailbox full

Recipient mailbox has exceeded storage quota.

Action: Remove from list. Don't retry - storage doesn't free up.

550 5.7.1 Authentication failed

SMTP authentication failed. Invalid credentials.

Action: Verify your username and password. Regenerate API key.

550 5.1.1 User unknown

Recipient email address doesn't exist.

Action: Remove from list immediately. Never retry this address.

550 5.1.6 Spam not accepted

Content detected as spam by recipient ISP.

Action: Review content, check for spam triggers, verify sending reputation.

550 5.7.26 Service refused

Your sending domain or IP has been blocked.

Action: Check for blacklisting. Contact support if issue persists.

554 5.7.1 Message blocked

Message blocked due to policy or content policy.

Action: Review content, remove problematic links/text, check authentication.

API Errors

{ "success": false, "error": { "code": "error_code_name", "message": "Human readable message", "details": "Additional context" } }

invalid_api_key

The API key provided is invalid or expired.

Action: Regenerate your API key in the dashboard.

invalid_recipient

The recipient email address has invalid syntax.

Action: Validate email addresses before sending.

domain_not_verified

The sending domain hasn't been verified.

Action: Complete domain verification in dashboard.

ip_not_warmed

The sending IP hasn't completed warmup.

Action: Wait for warmup completion or contact support.

rate_limited

You've exceeded your sending rate limit.

Action: Implement rate limiting in your code. Retry after delay.

attachment_too_large

Email attachment exceeds 10MB limit.

Action: Reduce attachment size or use file hosting link.

daily_quota_exceeded

Daily sending quota has been reached.

Action: Upgrade plan or wait for quota reset at midnight UTC.

Troubleshooting Checklist

Before Contacting Support

  1. Check SMTP response code and message
  2. Verify credentials are correct
  3. Check domain authentication (SPF/DKIM/DMARC)
  4. Verify IP reputation at postmaster tools
  5. Check for blacklisting at mxtoolbox.com
  6. Review recent sending patterns for violations