Skip to main content

Extended Error Codes

Last updated August 2021

When developing to the REST api, you should be prepared to handle failed requests, understand their meaning and what actions are needed to resolve them. It is useful to have a general understand the meaning of certain types of HTTP codes. You may read more about what HTTP Status Codes are generally defined and the following provides some rules of thumb for what certain types of codes mean.

  • 2xx means that the API call was successful
  • 4xx means that there was a problem with the call. You need to fix something before retrying. Usually the extended error code or message in the HTTP response body will indicate the problem. If you are not able to figure out how to fix the call then contact Support with details on the API call and current response.
  • 5xx means that there is a problem with the SparkPost service. Usually it is a transient error that will work on retry. If the call fails with a 5xx after 2 retries then contact Support.

Extended Error Code Details

The following table is a complete list of extended error code responses, organized by the four elements included in the response array.

  • Component: The related service that the error has sourced from
  • Error Code: The numeric code of the extended error
  • Notes: The human readable description of the error
  • HTTP Status Code: The server level response
ComponentError CodeNotesHTTP Status CodeCorrective Action
API Service1000-1999
1000OK200
1001OK (delete)204
1100permission denied403check API key, retry
1101invalid URI404fix URI and retry
1102invalid HTTP method405
1103invalid query string404
1200invalid params400
1300invalid data format/type/length422fix request and retry
1301Invalid combination of fields422
1303Invalid customer id, unauthorized tenant.401
1304Invalid User ID, unauthorized user.401
1305Input Data not UTF8 encoded400
1400Required field is missing422
1401Required parameter missing400
1500Failed to update database500
1501Failed to read from database500
1502Server resources unavailable400retry later
1600resource not found404correct uri and retry
1601No license403
1602Resource in use409
1603Subresource not found422
1700Unsupported Content-Type header415fix content-type and retry
1800HTTP header value not acceptable406fix header and retry
1900Message generation module not available503retry, likely transient error
1901Message failed to generate400
1902Message generation rejected400
1910Message generation not configured400
Transmission2000~2999
2000transmission created, but with validation errors200check for validation errors, retry if needed
2001Invalid transmission id400
2002Substitution data too large422
2003Too close to generation time to delete409
2004No draft version of template exists422
2005No published version of template exists422
2006Transmission record in invalid state409
2101Exceed Sending Limit (hourly)420
2102Exceed Sending Limit (daily)Deprecated
2103Exceed Sending Limit (sandbox)420
2106Invalid Template ID (sandbox)422
Template3000~3999
3000template language syntax error422fix content and retry
3001template language render error422fix content and retry
3002Invalid header422correct header and retry
3010template mime construction error422fix content and retry
3020template mime parsing error422fix content and retry
3030template already exists400
3040template content is corrupt422fix content and retry
3050template HTML content is invalid422fix content and retry
Recipient List5000-5999
5000List created with validation errors200
5001List already exists400
5002No valid recipients in list400
Engagement Tracking6000-6999
6100Tracking domain exists400
6200Tracking domain does not exist404
Sending Domain7000-7999
7000Sending domain blacklisted400
7001Invalid Sending/Tracking Domain400
Any Rate limited APIToo many requests429Rate limiting - pause and retry
Relay Webhooks10000-10002
10000Using a restricted custom header422remove the restricted header and retry
10001Total size of custom headers is too large413reduce the size of the custom headers and retry
10002Using more than the maximum amount of headers allowed422reduce the number of custom headers and retry
Was this page helpful?