API & Integrations - Troubleshooting Common HTTP Error Codes

Updated May 13, 2026 13:41

This article contains information on troubleshooting Mimecast API HTTP errors, their causes, sub-codes, and resolution steps to help maintain reliable integrations.

Overview

When integrating with Mimecast's API, you may encounter HTTP error codes indicating issues with your requests. Understanding these error codes is crucial for efficient troubleshooting and maintaining reliable API integrations. This article covers all common HTTP error codes, their Mimecast-specific sub-codes, root causes, and resolution steps.

This article applies to both API 1.0 (Email Security - AP) and API 2.0 (Email Security - MX) unless otherwise noted. For API setup and key management, see the Managing API Applications.

Prerequisites

Before troubleshooting API errors, ensure you have appropriate permissions within your Mimecast account, access to the Mimecast Administration Console, API testing tools such as Postman (recommended), and the relevant Mimecast API documentation for your endpoints.

Quick Reference

Use this table for a rapid overview. Refer to the Detailed Error Code Reference below for full troubleshooting steps.

Code	Status	Meaning	Action
400	Bad Request	Invalid request payload, missing fields, or malformed JSON.	Validate payload against API docs.
401	Unauthorized	Authentication failure — credentials missing, invalid, or expired.	Verify credentials and regenerate keys.
403	Forbidden	Authorization failure — valid credentials but insufficient permissions.	Check user roles and API application permissions
405	Method Not Allowed	Incorrect HTTP method (e.g., GET instead of POST).	Use POST for all API 1.0 endpoints; check docs for 2.0.
418	AccessKey Expired	Access key has exceeded its time to live.	Regenerate keys: set Auth Profile TTL to Never Expires.
429	Too Many Requests	API rate limit exceeded.	Implement backoff; increase polling intervals.
500	Internal Server Error	Server-side processing error.	Retry with backoff, check Mimecast Status Page.

Detailed Error Code Reference

The table below provides comprehensive troubleshooting guidance for each HTTP error code and Mimecast-specific sub-code. Impact is rated as High (service-blocking), Medium (degraded functionality), or Low (cosmetic or easily resolved).

HTTP Code	Sub-Code	Description	Common Causes	Resolution Steps	Impact
400 Bad Request
400	-	Invalid request payload or parameters	• Malformed JSON body • Missing required fields • Invalid date range or format • Unsupported Accept type header	• Validate JSON syntax (use a linter or Postman) • Cross-check required fields against API documentation • Verify date formats match ISO 8601 (YYYY-MM-DDTHH:mm:ssZ) • Ensure Accept header is application/json	Low
400	validation_error	Request validation failure	• Field value out of accepted range • Invalid email format in request body • Missing X-Request-Id header (specific APIs)	• Review the error[].field value in the response for the failing field • Check the error[].message for human-readable details • Add any missing request headers per endpoint docs	Low
401 Unauthorized — Authentication Failures
401	0003	Invalid Credentials	• Incorrect username or cloud password • User account disabled or locked • SAML/SSO used for service account (not supported for API)	• Verify the service account email and cloud password • Confirm the account is active in the Mimecast Administration Console • Use cloud authentication, not SAML/SSO, for API service accounts	High
401	0004	Invalid Signature	• Access key or secret key is incorrect • Request signing algorithm mismatch • Clock skew between client and server	• Regenerate access and secret keys • Verify HMAC-SHA1 signing implementation • Ensure client system clock is accurate (NTP sync)	High
401	0008	AccessKey Cannot Be Refreshed	• Access key is permanently invalid • Key was generated against a now-disabled account	• Generate a new set of access and secret keys • Verify the service account is active and has a valid auth profile	High
401	0010	Login Locked Out	• Too many failed authentication attempts • Automated script retrying bad credentials	• Wait for the lockout period to expire (typically 30 mins) • Unlock the account via the Mimecast Administration Console if available	High
401	0012	Remote Wipe Requested	• A remote wipe has been issued for the device or binding	• Contact your Mimecast administrator to review the wipe request • Re-bind the application if the wipe was intentional	High
401	0013	Binding Not Found	• Binding was revoked by an administrator • Binding expired due to prolonged inactivity • Keys generated against a deleted application	• Re-create the API application and generate new keys • Ensure the Authentication Profile TTL is set to Never Expires • Verify the application still exists in Services \| API Applications	High
403 Forbidden — Authorization Failures
403	0002	Forbidden To Perform Operation	• API user lacks the required role or permissions • Custom admin role missing specific API permissions • Account-level restrictions on the endpoint	• Assign the Basic Administrator role (recommended) or verify custom role permissions • Check the endpoint's required permissions in the API documentation • Confirm the user belongs to the correct API Admin Group	High
403	0009	Password Expired	• The service account's cloud password has expired • Password policy forced a reset	• Reset the cloud password for the API service account • Regenerate access and secret keys after password reset • Consider using an Authentication Profile with no expiry	High
403	0012	Too Many Application Bindings	• Maximum number of bindings reached for the user • Old bindings not cleaned up	• Remove unused bindings via the Mimecast Administration Console by navigating to Account \| Account Settings \| User Access • Consider using a dedicated service account per integration	Medium
405 Method Not Allowed
405	—	Incorrect HTTP method used for the endpoint	• Using GET, PUT, or DELETE instead of POST • Incorrect endpoint URL causing routing to wrong handler • Trailing slashes or typos in the request URL	• All Mimecast API 1.0 endpoints require POST — verify the method • For API 2.0, check the documentation for the correct method per endpoint • Validate the full endpoint URL matches the documentation exactly • Test the request in Postman to isolate script vs API issues	Low
418 AccessKey Expired
418	0001	AccessKey Has Expired	• Access key exceeded its TTL (time to live) • Authentication Profile TTL is not set to Never Expires • User password was changed, invalidating all keys	• Generate new access and secret keys • Move the API service account to an Authentication Profile with TTL set to Never Expires • Do not change the service account password without regenerating API keys • For Splunk/SIEM integrations, update the stored credentials immediately	High
429 Too Many Requests
429	—	Rate limit exceeded	• Too many API calls within the rate window • Aggressive polling interval on SIEM or log collection • Multiple integrations sharing the same API credentials	• Implement exponential backoff and retry logic • Increase polling intervals (recommended: 300 seconds minimum for SIEM) • Use separate API credentials per integration where possible • Review the Retry-After header in the response for wait time	Medium
500 Internal Server Error
500	—	Server-side error	• Transient infrastructure issue on Mimecast's side • Timeout on backend service processing • Malformed request that bypasses validation	• Retry the request with exponential backoff • Check the Mimecast Status Page for any active incidents • If persistent, capture the request ID and contact Mimecast Support • Review the request payload for unusual or oversized data	High

API 1.0 vs API 2.0 Key Differences

Error behavior may differ between API versions. The table below highlights the key differences that affect troubleshooting.

Aspect	API 1.0 (Email Security - AP)	API 2.0 (Email Security - AP / Email Security - MX)
Authentication Method	Application ID/Key + Access/Secret Key (HMAC-SHA1 signed)	OAuth 2.0 Client Credentials (Client ID + Client Secret)
Base URL	Region-specific (e.g., https://us-api.mimecast.com)	Global: https://api.services.mimecast.com
HTTP Methods	POST only for all endpoints	Mixed (GET, POST, PUT, DELETE per endpoint)
Error Format	Meta status code + fail[] array in response body	Standard HTTP status + error[] array with code, message, field
Key Regeneration	Regenerate Access/Secret keys via Admin Console	Regenerate Client ID/Secret

General Troubleshooting Checklist

Before diving into error-specific troubleshooting, work through the following checklist to eliminate common issues.

Check	Action
Verify API Credentials	Confirm Application ID, Application Key, Access Key, and Secret Key are correct and current.
Check User Permissions	Ensure the service account has the Basic Administrator role (or appropriate custom role with the required API permissions).
Validate Authentication Profile	The API service account must belong to an Authentication Profile with the TTL set to Never Expires to prevent key expiry.
Confirm API Admin Group Membership	The service account email address must be added to the API Administrator Group in the Mimecast Administration Console.
Verify Endpoint and Base URL	Use the correct base URL for your account region and confirm the endpoint path matches the API documentation.
Check Account Type Compatibility	Verify whether the endpoint is available for your account type (Email Security - MX vs Email Security - AP).
Test in Postman	Isolate script issues by reproducing the API call in Postman with the same headers, body, and credentials.
Review Admin IP Ranges	If applicable, confirm the source IP of API calls is permitted under Account Settings \| User Access and Permissions.
Check Mimecast Status Page	For 500 errors or intermittent failures, verify there are no active incidents or maintenance windows.
Capture the Request ID	Include the x-mc-req-id from the response headers when raising a Mimecast Support case for faster investigation.

When to Contact Mimecast Support

If you have worked through the relevant troubleshooting steps above and the issue persists, raise a case with Mimecast Support. To help expedite resolution, include the following information with your case: the full HTTP response including status code and body, the x-mc-req-id request ID from the response headers, the API endpoint URL and HTTP method used, the approximate timestamp and time zone of the failed request, and your Mimecast Account Code.

For information on raising a support case, see Mimecast Customer Care - Raising a Case