The Marketo REST API may return an exception or error, which, for convenience, we will just call errors from here on out. Errors can occur at three different levels:
- 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
HTTP Errors
Under normal operating circumstances Marketo should only return two HTTP status 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 8KiB. 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
Response level errors are present when the “success” parameter of the response is set to false. Each entry in “errors” has two members, “code” a number, either 6xx or 7xx, 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.
Record-Level Errors
Record level errors indicate that an operation could not be completed for an individual record, but the request itself was valid. These occur within individual record 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 Create/Update 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.”
In the next few posts, we will take a look at recoverable errors, and some examples of how to handle these inside of your code.