REST API response codes
REST API response codes can be found in the Status line of a HTTP response message. Their purpose is to provide information about the results of a request, which can help developers manage and troubleshoot activity and errors on their apps.
The most common API response codes you might see are listed below with an explanation of what they mean and some suggestions of what might be causing the response. Sometimes there is further information accompanying the error, and you'll find some examples of this below.
200 - OK
Good news! The request is formatted correctly and the requested action should be taken/data returned. This is the positive response for most PUT, GET, and some POST requests in the API documentation.
201 - Created
This means there were no issues found with the request and the requested action has been taken. The 201 response will appear on some API requests, such as successful POST requests to our webhooks and inbound routes endpoints.
202 - Accepted
202 responses may occasionally have a response body, here are some examples:
This is the accompanying response for successful API requests sent to the bulk-email endpoint. Each bulk email request will have a unique bulk_email_id.
If all or some of the recipients in the email list have been suppressed, a variation of this message will be sent back in response. There will always be a 202 response, but the email won’t be sent if all recipients are suppressed.
204 - Success
And similar to the 200 and 201 responses, this means there were no issues found with the request and the requested action has been taken.
400 - Bad request
Bad request errors normally indicate a server-side problem. If you are still faced with this error after trying again, contact the technical support team.
401 - Unauthorized
This response will nearly always be accompanied by the following response body message:
This normally suggests an issue with the token you have provided. To troubleshoot, check the following:
If everything is in order, try creating a new token and attempt the request again to see if this resolves the issue.
403 - Forbidden
403 indicates an issue with the request or the account attached to the request. Several different messages can appear on a 403 response.
“Your account is suspended": If you attempt to send a request with a suspended account, you will receive this response and the request will not be fulfilled.
"Invalid scope(s) provided": This could indicate that you are using a custom API token that doesn't have the required permissions.
For example, if you’re sending a request to the email endpoint using a token that does not allow email access. If you receive this error, check that you are using a token that has the required access.
"This action is unauthorized": This message will be returned if a rejected account tries to send a request to the email endpoint.
"You do not have permission to add another domain”: Multiple domains is a premium feature. Free and no plan accounts will see this message if they try and add an additional domain via API.
"This account access is blocked. Contact support”: This error message is returned if API/SMTP access has been switched off for your account.
"You've reached the webhook limit. Upgrade to add more webhooks”: Free and no plan accounts can add 1 webhook. If a free/no plan account holder attempts to add more than 1 webhook, they will receive this message.
404 - Not found
This is a standard 404 message. It means the endpoint URL you are attempting to send a request to cannot be found.
Check the URL and the URL formatting. If the URL is correct, contact support.
405 - Method not allowed
In the unlikely event that you receive this response code, please contact support.
408 - Request timeout
Like the 400 bad request response, request timeout errors normally indicate a server-side problem. If you continue to receive this response, please contact support.
422 - Unprocessable entity - validation error
422 usually means the API call has not been correctly formatted and/or there is a validation error due to the reasons outlined below.
As stated, this will be sent in response if an attachment is included and its size exceeds the 10MB threshold.
These messages can appear in response to a POST request sent to the email endpoint with the required parameters missing.
It is also not uncommon to see this message when these parameters have been added. This may indicate they have been added incorrectly or there is a problem with the formatting of the code.
At least one of the following must be added to a send an email request for it to be successful: html version, text version, or template_id. If none of these are added to the request then this message will be returned.
As with the similar message above, it is not uncommon to see this message when these parameters have been added, which may indicate they have been added incorrectly or there is a problem with the formatting of the code.
If the to.*.email is duplicated in a send an email request, this message will be returned.
The domain on the from.email must be verified on your account to be able to send emails. Please make sure this domain has a "is_verified" value set to 'true' via the API or the app. You can also add the from email address as a sender identity if you're on a Premium plan.
Supported file types are listed here.
This response is given when an account's quota has been reached.
This response is sent if the limit of CC and BCC recipients in a single email object is reached. The limits are as follows:
Approved accounts: Up to 10 BCC recipients and up to 10 CC recipients per email object.
Not yet approved accounts: Up to 1 BCC recipient and up to 1 CC recipient per email object.
This error could mean the file name you have entered does not match. For example, if you have uploaded a GIF file but entered the file name as "me.png".
429 - Exceeded limit
Every request is counted against the quota and is reset daily at midnight UTC:
Accounts with no plan have a limit of 100 API requests per day. Free plan accounts are limited to 1000 requests per day. Premium plans can send up to 100,000 requests per day, and Enterprise 100,000+.
This response will be sent back if you attempt to send requests to our API more frequently than we allow:
MailerSend has a default rate limit of 60 requests per minute on general API endpoints and 120 for email endpoints. Please wait for the amount of seconds indicated by 'retry-after' and try again.
500 - Server error
A 500 response indicates a server-side error. If you continue to receive this error, please contact support.