Mailchimp Developer Homepage

Errors

The basics

The Mailchimp Marketing API will return a variety of errors if anything goes wrong with your API calls. Every error has a numerical 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:

Error – HTTP Response

Plain Text
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://us2.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=/

Error – JSON

JSON
{ "type": "https://developer.mailchimp.com/documentation/mailchimp/guides/error-glossary/#405",
  "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": ""
}

Common causes

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

5xx error 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 or are currently offline for planned maintenance. 

If an error returns HTML instead of JSON, your request may have timed out. Contact our support team, and note the Ref# provided in the error.

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

ErrorDescription

400

BadRequest: Your request could not be processed.

This is a generic error.

InvalidAction: The action requested was not valid for this resource.

This error is returned when you try to access an action that doesn’t exist.

InvalidResource: The resource submitted could not be validated.

For field-specific details, see the field_warnings or field_errors objects. This error means that the object submitted to a POST or PATCH request failed to validate against the JSON schema, and could relate to a campaign, interest group, merge field, or any other available object.

JSONParseError: We encountered an unspecified JSON parsing error.

This error means that your JSON was formatted incorrectly or was considered invalid or incomplete. 

401

APIKeyMissing: Your request did not include an API key.

This error suggests that your API key was missing from your request, or that something was formatted or named improperly in your header. To learn more, check out the Marketing API Quick Start

APIKeyInvalid: Your API key may be invalid, or you’ve attempted to access the wrong data center.

Check that your API key was input correctly, and verify which data center to access. To learn more, check out the authentication fundamentals.

403

Forbidden: You are not permitted to access this resource.

This is a generic error.

UserDisabled: This account has been disabled.

The Mailchimp account is deactivated. Contact our support team if you need more help.

WrongDatacenter: The API key provided is linked to a different data center.

This error suggests that you tried to contact the wrong data center. It’s often associated with misconfigured libraries.

404

ResourceNotFound: The requested resource could not be found.

This error tells you a specific resource doesn’t exist. It’s possible that the resource has been moved or deleted, or that there’s a typo in your request.

405

MethodNotAllowed: The requested method and resource are not compatible. See the Allow header for this resource’s available methods.

This error means that the requested resource does not support the HTTP method you used. Find out which methods are allowed for each resource in the API reference.

414

ResourceNestingTooDeep: The sub-resource requested is nested too deeply.

This uncommon error appears if you’ve tried to generate a URL with too many resources, or if you’ve made a request to a malformed URL.

422

InvalidMethodOverride: You can only use the X-HTTP-Method-Override header with the POST method.

This error lets you know you’ve tried to override an incompatible method. The Marketing API only permits method override with POST.

RequestedFieldsInvalid: The fields requested from this resource are invalid.

This error suggests there is a typo or syntax error in your field request.

429

TooManyRequests: You have exceeded the limit of 10 simultaneous connections.

When you reach the connection limit, we’ll throttle server response. If any of your requests time out after you’ve reached the limit, those requests could still be considered open and continue to slow your connection. Contact the Marketing API support team at apihelp@mailchimp.com if you think this is the case.

500

InternalServerError: An unexpected internal error has occurred. Please contact Support for more information.

This error lets you know our servers have experienced a problem. Although this is rare, please contact apihelp@mailchimp.com to let us know that you’ve encountered this error.

503

ComplianceRelated: This method has been disabled.

You will see this error if your account is under compliance review.