Error Codes

Marketo REST APIs return errors at the HTTP, response, or record level. This page explains each error type and lists the associated error codes.

Handling and Logging Exceptions

Log requests and responses when your integration encounters an unexpected exception. Some exceptions, such as expired authentication, can be handled by re-authenticating. Other exceptions can require assistance from Support, which will request the associated request and response details.

Error Types

The Marketo REST API can return three types of errors during normal operation:

Response-Level and Record-Level errors return HTTP status code 200. For all error types, do not evaluate the HTTP reason phrase because it is optional and subject to change.

HTTP-Level errors

During normal operation, Marketo returns two HTTP status code errors: 413 Request Entity Too Large and 414 Request URI Too Long. To recover from either error, modify the request and retry it. You can prevent these errors by checking request sizes before submission.

Marketo returns 413 when the request payload exceeds 1MB, or 10MB for Import Lead. Check the request size before submission. If records cause the request to exceed the limit, move those records to another request.

Marketo returns 414 when the URI of a GET request exceeds 8KB. Check the query-string length before submission. If it exceeds the limit, change the request method to POST, put the query string in the request body, and add the _method=GET parameter. Long URIs are most common when retrieving large record batches with long filter values, such as a GUID.

The Identity endpoint can return a 401 Unauthorized error, typically because the Client Id or Client Secret is invalid. The following table lists HTTP-Level error codes.

Response-Level errors

Response-Level errors occur when the response sets the success parameter to false. They use the following structure:

{
    "requestId": "e42b#14272d07d78",
    "success": false,
    "errors": [
        {
            "code": "601",
            "message": "Unauthorized"
        }
    ]
}

Each object in the “errors” array contains two members:

A 6xx code indicates that the entire request failed and was not executed. For example, recover from a 601 “Access token invalid” error by re-authenticating and passing the new access token with the request.

A 7xx code indicates that the request failed because no data was returned or the request parameters were invalid. Causes include an invalid date or a missing required parameter.

Response-Level Error Codes

Record-Level record_level_errors

Record-Level errors indicate that the request was valid but the operation could not be completed for an individual record. A response with Record-Level errors follows this pattern:

Response

{
   "requestId":"e42b#14272d07d78",
   "success":true,
   "result":[
      {
         "id":50,
         "status":"created"
      },
      {
         "id":51,
         "status":"created"
      },
      {
         "status":"skipped",
         "reasons":[
            {
               "code":"1005",
               "message":"Lead already exists"
            }
         ]
      }
   ]
}

Records in the result array appear in the same order as records in the request input array. Each record can succeed or fail independently, as indicated by its status field.

For a failed record, the “status” field is “skipped” and the record includes a “reasons” array. Each reason contains a “code” member and a “message” member. The code is always 1xxx, and the message explains why the record was skipped.

For example, if a Sync Leads request sets “action” to “createOnly” and a lead already exists for one of the submitted keys, the response returns code 1005 and the message “Lead already exists,” as shown above.

Record-Level Error Codes