Mailchimp Developer Documentation

The basics

The Mailchimp Marketing API will return a variety of errors if anything goes wrong with your API calls. Every error has an HTTP status code, and will also return an error type and brief explanation when the error is triggered. This documentation provides additional explanations of these errors and guidance on how to avoid them.

When you use any API, keep in mind that errors and exceptions (e.g., server connection problems or outages) are rare, but they do happen. To make sure that your integration is as reliable as it can be, you should always watch for errors and exceptions.

If your API call returns an error, log the call in as much detail as you can. If you need to contact support, we recommend including the complete request you’re trying to make, the error code, and the response you’re receiving so they can help as quickly as possible.

Error format

We expose API errors in two ways: standard HTTP response codes and human-readable messages in JSON format.

Here’s an HTTP 405 error in both formats:

HTTP/1.1 405 Method Not Allowed
Server: nginx
Content-Type: application/problem+json; charset=utf-8
Content-Length: 253
X-Request-Id: a1efb240-f8d8-40fe-a680-c3a5619a42e9
Link: <https://api.mailchimp.com/schema/3.0/ProblemDetailDocument.json>; rel="describedBy"
Date: Thu, 17 Sep 2015 19:02:28 GMT
Connection: keep-alive
Set-Cookie: _AVESTA_ENVIRONMENT=prod; path=/

{
    "type": "/marketing/api-concepts/errors",
    "title": "Method Not Allowed",
    "status": 405,
    "detail": "The requested method and resource are not compatible. See the Allow header for this resource's available methods.",
    "instance": "3b4dcb40-0b6b-4820-bfaa-41267b3826ea"
}

Common causes

4xx status codes suggest a bad request. If you receive a 4xx response, the error glossary below offers more context to help you troubleshoot.

5xx status codes suggest a problem on Mailchimp’s end. If you receive a 5xx error, we recommend checking @MailchimpStatus on Twitter to see if we are experiencing any system-wide issues.

If you receive an HTTP 502 error with an HTML body, your request may have timed out and been closed by our CDN. Contact support for help resolving.

To test error handling, you can trigger errors yourself by sending an X-Trigger-Error header with the name of the error. For example, sending a value of APIKeyMissing in the X-Trigger-Error header will trigger a 401 error.

Error glossary

Error	Description
400	There are several different error titles returned for 400 errors, which will return an explanation in the “detail” field. Some of the most notable include: Bad Request This is the generic error type for not being able to process the request, and will generally contain an explanation in the message. Invalid Resource The submitted POST body failed our input validation. This error may include an additional “errors” property, with a list of the validation issues. Invalid Action: The action requested was not valid for this resource. Returned when you try to access an action on a resource that doesn’t support that action. JSON Parse Exception The JSON sent in the request body is not valid JSON.
401	API Key Invalid The API key is either invalid or disabled; there will be more information in the “detail”. For help authenticating with the Marketing API, see the Quick Start guide.
403	Forbidden Either the user who created the API key no longer has access to the account, or their user level doesn’t allow access to the endpoint; there will be more information in the “detail”. For user levels, the role of the API key is returned from the Root endpoint. Note that a user’s level can change, changing the access of the API key as well. User Disabled: This account has been deactivated. The Mailchimp account is deactivated. Contact support if you need more help. Authorization Failure: User does not have access to the requested operation Your account’s pricing plan may not permit access to a feature; upgrading the account’s plan may fix these errors.
404	Resource Not Found: The requested resource could not be found. Either no object exists with the ID provided in the path, or the path is incorrect.
405	Method Not Allowed This error is usually due to the endpoint not supporting the request’s HTTP method; find out which methods are allowed for each resource in the API Reference. It also might be returned due to restrictions on the action because of the state of the resource—for example, campaigns that are currently sending cannot be deleted. The restriction will be provided in the “detail”.
414	Resource Nesting Too Deep: The sub-resource requested is nested too deeply. Occurs when a URL has too many path segments or is malformed.
422	InvalidMethodOverride: You can only use the X-HTTP-Method-Override header with the POST method. The Marketing API only permits method override with POST; read about the X-HTTP-Method-Override in our HTTP Method documentation.
426	Your request was made with the HTTP protocol. Please make your request via HTTPS rather than HTTP. The Marketing API requires requests be made with TLS 1.2 or higher. Please try your request again. Note that the response code currently is returned as a `426 Unknown` but is intended to be `426 Upgrade required`.
429	TooManyRequests: You have exceeded the limit of 10 simultaneous connections. The Marketing API sets a limit of 10 simultaneously processing requests per user. Additional requests over the limit receive a 429 response. Note that: The limit is per user, and not per API key or per client.The length of time it takes a request to run will affect how many requests you can make in a given time period.Requests may time out for you, but still be running on our backend, reducing the available connections. TooManyRequests: You have more than 500 pending webhooks. Please wait for some to complete before adding any more batches. The Marketing API sets a limit of 500 pending batch webhook events per user. Batch API requests that are submitted while there are still outstanding batch webhook events will receive a 429 response. Note that: For every batch operation that is completed, one batch webhook event is created for every batch webhook on the account. You can see your configured batch webhooks by using the Batch Webhook endpoint.This error type will only be returned when creating new batch operations, using the Start Batch Operation endpoint.
500	InternalServerError: A deep, internal error has occurred during the processing of your request. Please contact support. This error lets you know our servers have experienced an unexpected problem. We automatically monitor for this type of error internally. Check @Mailchimp Status for any active incidents, or reach out to support if your issue persists outside of an incident.