Quick Answer
Match the Mailgun error code to the sections below. Check request formatting and required parameters for 400-series errors, sending limits for 429 errors, and Mailgun service availability for 500 errors.
How to Use This Library
When Mailgun returns an error, locate the corresponding status code below and review its likely causes and recommended fixes.
Many Mailgun errors can be resolved by checking required request parameters, email-address formatting, authentication credentials, domain status, DNS verification, and account limits.
Troubleshooting order: Start with request and configuration problems in the 400 series, check account or sending limits for 429, and then investigate Mailgun service problems for 500.
Error Codes at a Glance
400
Bad request
401
Unauthorized request
403
Restricted action
404
Domain not found
413
Request too large
429
Rate limit exceeded
500
Mailgun server error
Before Troubleshooting
Collect the information needed to identify whether the problem involves the request, account, domain, or Mailgun service.
- Record the complete error code and response message.
- Confirm which Mailgun domain and account generated the error.
- Check whether the sending domain is active and verified.
- Review recent changes to API keys, credentials, DNS records, or sending volume.
- Keep request details available if you need to contact Mailgun support.
400 Errors: Bad Request
A 400 error usually means that part of the request is missing, invalid, or incorrectly formatted.
Missing Required Parameters
Cause: The from, to, or message parameter is missing.
Fix: Add a valid sender, recipient, and required message content to the request.
Missing Text or HTML Content
Cause: The request does not include at least one text or html body.
Fix: Add a plain-text or HTML email body.
HTML and Template Conflict
Cause: The request includes both HTML content and a template where only one is allowed.
Fix: Use either the HTML body or the Mailgun template.
Too Many Recipients
Cause: The request exceeds the stated maximum of 1,000 recipients.
Fix: Reduce the number of recipients to 1,000 or fewer and divide larger lists into batches.
Invalid Email Address
Cause: An address in to, from, cc, or bcc is incorrectly formatted.
Fix: Correct the affected address and submit the request again.
Invalid or Malformed Request
Cause: The content type or multipart/form-data payload is incorrect.
Fix: Use the required content type and correct the formatting of the payload or file uploads.
Invalid Delivery Time
Cause: A scheduled message uses an invalid date or time format.
Fix: Correct the delivery-time format before resubmitting the request.
Account or Domain Limitation
Cause: A sandbox domain, free-account restriction, unverified domain, or inactive account is preventing the send.
Fix: Complete account activation, verify the domain, or review the Mailgun plan’s production-sending limits.
Quick check: Confirm the from and to values, make sure the message contains text or HTML content, and verify that the Mailgun domain is active.
401 Error: Forbidden or Unauthorized
A 401 error generally indicates an authentication or account-permission problem.
- Confirm that the request uses the correct API key.
- Check whether the API key was recently replaced or rotated.
- Review the account role and permissions of the user making the request.
- Confirm that the request uses the correct regional endpoint when applicable.
403 Errors: Restricted Action
A 403 error means Mailgun understands the request, but the requested action is blocked by a restriction or policy.
Large Batch Not Allowed
Reduce the batch size or confirm whether the account is permitted to send at the requested volume.
Unauthorized IP or Domain
Confirm that the sending IP and domain are authorized and review any restrictions applied to the account.
404 Error: Domain Not Found
This error usually means that the domain included in the request does not exist in the Mailgun account.
- Confirm that the domain appears under Domains in Mailgun.
- Review the domain name in the request for typing errors.
- Verify the domain’s DNS records and status if it was recently added.
413 Error: Request Too Large
A 413 error indicates that the request payload exceeds the permitted size, often because of one or more large attachments.
- Reduce the size or number of attachments.
- Compress images and documents when appropriate.
- Replace large attachments with downloadable file links when suitable.
429 Errors: Rate Limits
Mailgun can return a 429 error when a request, byte, or recipient limit is exceeded within a particular period.
Request Limit Exceeded
Wait until the limit resets, then retry the request at a lower frequency.
Byte Limit Exceeded
Reduce the request size or frequency and try again after the reset.
Recipient Limit Exceeded
Reduce the number of recipients per send and divide the campaign into smaller batches.
If 429 errors occur regularly, reduce the sending speed or divide campaigns into smaller controlled batches.
500 Error: Internal Server Error
A 500 error indicates a server-side problem at Mailgun rather than a normal request-validation error.
- Wait briefly and retry the request.
- Check Mailgun’s service status if the error continues.
- Save the complete error response and relevant request details.
- Contact Mailgun support if the problem persists.
Frequently Asked Questions
What does Mailgun error 400 mean?
It indicates a bad request, commonly caused by missing parameters, invalid email addresses, malformed request data, or an account or domain limitation.
What does Mailgun error 401 mean?
The request is not authorized. Check the API key, account credentials, permissions, and regional endpoint.
What does Mailgun error 403 mean?
The requested action is restricted. Review batch-size limits and confirm that the sending IP, domain, and account are authorized.
What does Mailgun error 404 mean?
The specified domain was not found in Mailgun. Confirm that it has been added, spelled correctly, and verified.
What does Mailgun error 413 mean?
The request is too large, often because of attachments. Reduce the total message or attachment size and try again.
What does Mailgun error 429 mean?
A request, byte, or recipient rate limit was exceeded. Wait for the limit to reset and retry using a lower volume or smaller batches.
What does Mailgun error 500 mean?
Mailgun experienced an internal server error. Retry later and contact Mailgun support if the problem continues.
