Below are lists of REST API error codes, and an explanation of how errors are returned back to applications.
The Marketo REST API can return three different types of errors under normal operation:
- HTTP-Level – These errors are indicated by a 4xx code.
- Response-Level – These errors are included in the “errors” array of the JSON response.
- Record-Level – These errors are included in the “result” array of the JSON response, and are indicated on an individual record basis with the “status” field and “reasons” array.
Under normal operating circumstances Marketo should only return two HTTP status code errors, 413 Request Entity Too Large, and 414 Request URI Too Long. These are both recoverable through catching the error, modifying the request and retrying, but with smart coding practices, you should never encounter these in the wild.
Marketo will return 413 if the Request Payload exceeds 1MB, or 10MB in the case of Import Lead. In most scenarios it unlikely to hit these limits, but adding a check to the size of the request and moving any records which cause the limit to be exceeded to a new request should prevent any circumstances which lead to this error being returned by any endpoints.
414 will be returned when the URI of a GET request exceeds 8KB. To avoid it, check against the length of your query string to see if it exceeds this limit. If it does change your request to a POST method, then input your query string as the request body with the additional parameter ‘_method=GET’. This forgoes the limitation on URIs. It’s rare to hit this limit in most cases, but is somewhat common when retrieving large batches of records with long individual filter values such as a GUID.
Response level errors are present when the “success” parameter of the response is set to false, and will be structured like this:
Each object in the “errors” array has two members, “code,” which is a quoted integer from 600 to 799 and a “message” giving the plaintext reason for the error. 6xx codes always indicate that a request failed completely and were not executed. An example of this is a 601, “Access token invalid,” which is recoverable by re-authenticating and passing the new access token with the request. 7xx errors indicate that the request failed, either because no data was returned, or the request was incorrectly parameterized, such as including an invalid date, or missing a required parameter.
Response-Level Error Codes
|413||Request Entity Too Large||Payload exceeded 1MB limit.|
|414||Request-URI Too Long||URI of the request exceeded 8k. The request should be retried as a POST with param _method=GET in the URL, and the rest of the querystring in the body of the request.|
|502||Bad Gateway||The remote server returned an error. Likely a timeout. The request should be retried with exponential backoff.|
|600||Empty access token||An Access Token parameter was not included in the request.|
|601||Access token invalid||An Access Token parameter was included in the request, but the value was not a valid access token.|
|602||Access token expired||The Access Token included in the call is no longer valid due to expiration.|
|603||Access denied||Authentication is successful but user doesn’t have sufficient permission to call this API. Additional permissions may need to be assigned to the user role.|
|604||Request timed out||The request was running for too long, or exceeded the time-out period specified in the header of the call.|
|605||HTTP Method not supported||GET is not supported for Sync Leads endpoint, POST must be used.|
|606||Max rate limit ‘%s’ exceeded with in ‘%s’ secs||The number of calls in the past 20 seconds was greater than 100|
|607||Daily quota reached||Number of calls today exceeded the subscription’s quota. The default subscription quota is 10,000/day.|
|608||API Temporarily Unavailable|
|609||Invalid JSON||The body included in the request is not valid JSON.|
|610||Requested resource not found||The URI in the call did not match a REST API resource type. This is often due to an incorrectly spelled or incorrectly formatted request URI|
|611||System error||All unhandled exceptions|
|612||Invalid Content Type||If you see this error, add a content type header specifying JSON format to your request. For example, try using “content type: application/json”. Please see this StackOverflow question for more details.|
|613||Invalid Multipart Request||The multipart content of the POST was not formatted correctly|
|614||Invalid Subscription||The destination subscription cannot be found or is unreachable. This usually indicates temporary inaccessibility.|
|615||Concurrent access limit reached||At most 10 requests can be processed by any subscription at a time. This will be returned if there are already 10 requests for the subscription ongoing.|
|701||%s cannot be blank||The reported field must not be empty in the request|
|702||No data found for given search scenario||No records matched the given search parameters|
|703||Feature is not enabled for the subscription||A beta feature that has not been in enabled in a user’s subscription|
|704||Invalid date format||A date was specified that was not in the correct format|
|709||Business Rule Violation||The call cannot be fulfilled because it violates a requirement to create or update an asset, e.g. trying to create an email without a template. It is also possible to get this error when trying to:
|710||Parent Folder Not Found||The specified parent folder could not be found|
|711||Incompatible Folder Type||The specified folder was not of the correct type to fulfill the request|
Record level errors indicate that an operation could not be completed for an individual record, but the request itself was valid. A response with record-level errors will follow this pattern:
"message":"Lead already exists"
Each record in a successful request may succeed or fail on an individual basis which is indicated by the status field of each record included in the result array of a response. The “status” field of these records will be “skipped” and a “reasons” array will be present. Each reason contains a “code” member, and a “message” member. The code will always be 1xxx, and the message will indicate why the record was skipped. An example would be where a Sync Leads request has “action” set to “createOnly” but a lead already exists for one of the keys in the submitted records. This case will return a code of 1005, and a message of “Lead already exists” as displayed above.
Record-Level Error Codes
|1001||Invalid value ‘%s’. Required of type ‘%s’||Error is generated whenever parameter value has type mismatch. For example string value specified for integer parameter.|
|1002||Missing value for required parameter ‘%s’||Error is generated when required parameter is missing from the request|
|1003||Invalid data||When the data submitted is not a valid type for the given endpoint or mode; such as when id is submitted for a lead with action designated as createOnly or when using Request Campaign on a batch campaign.|
|1004||Lead not found||For syncLead, when action is “updateOnly” and if lead is not found|
|1005||Lead already exists||For syncLead, when action is “createOnly” and if lead already exists|
|1006||Field ‘%s’ not found||An included field in the call is not a valid field.|
|1007||Multiple leads match the lookup criteria||Multiple leads match the lookup criteria. Updates can only be performed when the key matches a single record|
|1008||Access denied to partition ‘%s’||The user for the custom service does not have access to a workspace with the partition where the record exists.|
|1009||Partition name must be specified|
|1010||Partition update not allowed||The specified record already exists in a separate lead partition.|
|1011||Field ‘%s’ not supported||When lookup field or filterType specified with unsupported standard fields (ex: firstName, lastName ..etc)|
|1012||Invalid cookie value ‘%s’|
|1013||Object not found||Get object (list, campaign ..etc) by id will return this error code|
|1014||Failed to create Object||Failed to create Object (list, ..etc)|
|1015||Lead not in list||The designated lead is not a member of the target list|
|1016||Too many imports||There are too many imports queued. A maximum of 10 is allowed|
|1017||Object already exists||Creation failed because the record already exists|
|1018||CRM Enabled||The action could not be carried out, because the instance has a native CRM integration enabled.|
|1019||Import in progress||The target list is already being imported to|
|1020||To many clone to program||The subscription has reached the alotted uses of cloneToProgramName in Schedule Program for the day|
|1021||Company update not allowed||Company update not allowed during syncLead|
|1022||Object in use||Delete is not allowed when an object is in use by another object|
|1029||Too many jobs in queue||Subscriptions are allowed a maximum of 10 bulk extract jobs in the queue at any given time.|
|1035||Unsupported filter type||In some subscriptions, the following Bulk Lead Extract filter types are not supported: updatedAt, smartListId, smartListName.|
Handling and Logging Exceptions
When developing for Marketo, it’s very important that requests and responses get logged when an unexpected exception is encountered. While certain types of exceptions, such as expired authentication can be safely handled by reauthentication, others may require support interactions, and requests and responses will always be requested in this scenario.