Marketo REST API Exception and Error Handling: Part 2

October 30, 2015 | by

Read Part 1 here

For the most part, errors received back from the Marketo REST API will not be automatically recoverable.  However, there are a handful of cases where you can recover automatically, or ensure you never see a certain type of error.

Request-Size Errors

As we looked at in the last post of this series, Marketo will emit HTTP Status code 414 if your URI exceeds 8KiB in length, or 413 if your request body exceeds 1MB, or 10MB for Import Lead.  Though 414s will be rare, you might see them if you’re using Get Leads By Filter type to request records based on 300 separate GUIDs or similar criteria.  Say you have the following request:,company…firstName,lastName

When you submit the request, Marketo returns a status of 414 because the URI exceeds 8KiB.  To handle this, we need to alter the pattern of this request, and submit a POST instead of a GET, append ‘_method=GET’ to the URI, and pass the querystring in the request body as a x-www-form-urlencoded request instead:


Request Body:


Instead of catching this exception from the HTTP response, however, we can just check the total length of the request at runtime, and deploy this alternative pattern if the URI exceeds 8k.  Alternatively, you could use the POST Method in all cases for batch retrievals of records.

For 413s, we can follow a similar pattern, checking the length of the request body when adding records during the serialization step, and splitting the request into multiple parts if this limit would be exceeded.

Authentication Errors

Our next class of recoverable errors is related to authentication.  When a formerly valid access token is used after its expires_in period has elapsed, the first usage will return an error code of 602, “Access token expired.”  After this, using the same token will return a 601, “Access token invalid.”  Any other usage of a string which is not a valid access token for the target subscription will result in a 601.  In both cases, this error can be recovered from by reauthenticating and passing the new access token with a retry of the failed request.


In very rare circumstances, a call may return a 604, “Request timed out,” after the 30 second timeout period has elapsed.  For batched requests, such as Create/Update Leads, the request can be split up into smaller batches and retried until success is returned (if the batch is split to less than 100 records and the request is still timing out, you should probably file a support case).  The most common other case is with asset approval calls, where a lock may be held on the current approved record by another user or service, such as the case of an Email or Email Template.  In these cases, exponential backoff should be used for retries to allow for any existing locks to be resolved.

Check back in the coming weeks for the final part of the series where we’ll take a closer look at some specific, non-recoverable errors.