403, 422, & 429 errors

If you've encountered 403, 422, or 429 errors while using MailerSend's API, it's important to understand what these errors indicate, as well as the rate limits and quotas associated with your plan.

403 - Forbidden errors

What it means: A 403 Forbidden error indicates that you're trying to access a resource on the server that you're not authorized to access. Unlike 401 Unauthorized errors, where authentication might solve the problem, a 403 Forbidden error signifies that authentication won't help. Your credentials may be valid, but you still don't have permission for a specific request.

Common scenarios

• Invalid API Key: If the API key you're using is invalid, expired, or revoked, you might encounter a 403 error

• Insufficient permissions: Your API key might be valid but lacking the necessary permissions to perform a specific operation

• Account status: If your MailerSend account is suspended, under review, or otherwise restricted, API calls may result in 403 errors

• IP blocking: If requests are coming from an IP address that has been blocked due to suspicious activity, you might get a 403 error

How to reduce 403 errors

• Check API Key: Make sure that your API key is correct, active, and not expired

• Review permissions: Ensure your API key or user account has the permissions necessary for the action you're trying to perform. You may need to generate a new key with broader permissions

• Check account status: Make sure your account is active and in good standing

• Examine IP Address: Confirm your IP address is not on any blocklists

• Check Endpoint URLs: Make sure you're requesting an existing endpoint and that the URL is spelled correctly

• Consult documentation: Always refer to MailerSend’s API documentation to ensure you're making requests correctly

422 - Validation errors

What it means: This error means a validation error was found when processing your request.

How to reduce 422 errors

• Ensure your API requests are formatted correctly and all required parameters have been included

• Refer to MailerSend's developer documentation for sample code and guidelines

• If you're using MailerSend templates, ensure that you're following the correct template structure

Response Code: 422 Unprocessable Entity
Response Headers:
	content-type: application/json

{
  "message": "The given data was invalid.",
  "errors": {
    "from.email": [
      "The from.email domain must be verified in your account to send emails. #MS42207"
    ]
  }
}

429 - Too many requests

Your account is generating a high rate of 429 error responses. This may be due to two main reasons:

• Either your account is sending more API or SMTP requests per day than our daily quota limits allow

• Or your account is sending more API or SMTP requests per minute than our rate limits allow

When you hit your daily quota or a rate limit, you will start receiving 429 HTTP error. Two HTTP headers will be returned with every API request to indicate the quota limit and when the quota will be reset.

Daily Quotas Limits

MailerSend has a daily request quota for API and SMTP relay services, which varies depending on your subscription plan. Every request made counts against your daily quota, which is reset daily at midnight UTC.

Plan	Quota / day
Trial	100
Free	100
Hobby	1,000
Starter	100,000
Professional	500,000
Enterprise	500,000

If you would like to increase your daily request limit and avoid any further disruption to sending, you can easily upgrade your plan.

HTTP/2 429
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 59
retry-after: 59
x-apiquota-remaining: 0
x-apiquota-reset: 2022-03-05T00:00:00Z

{
    "message": "Your account reached its API daily quota limit. Upgrade to increase it. #MS42901"
}

Tips

• Avoid sending repeated API requests that fail validation (HTTP 422 error)

• To track email activity and status, use webhooks

• If you are sending emails in bulk, use bulk endpoint

• For more throughput, upgrade to a professional plan.

Rate Limits

What it means: You've exceeded your rate limit per minute. This limit caps the number of API requests that can be made per minute.

For each MailerSend plan level, there are rate limits specified for different types of requests:

Endpoint	Healthy reputation	Under review reputation
All API requests (excluding v1/email)	60 requests per minute	60 requests per minute
API requests to v1/email	120 requests per minute*	10 requests per minute
API requests to v1/bulk	Free plan: 10 API calls/min Hobby plan: 10 API calls/min Starter plan: 15 API calls/min Professional plan: 30 API calls/min Enterprise plan: 60 API calls/min	1 request per minute

Please wait for the amount of seconds indicated by the retry-after response header and try again.

You can find more information about these limits in our developer documentation.

HTTP/2 429
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 0
retry-after: 59
x-ratelimit-reset: 1629291024

{
    "message": "Your account reached its rate limit of 120 requests/min. Please wait before trying again. #MS42903"
}

*Newly upgraded accounts may have a lower rate limit until they've been established as a sender with good sending practices.