Error Codes
Below are lists of REST API error codes, and an explanation of how errors are returned back to applications.
Handling and Logging Exceptions
When developing for Marketo, it’s 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 re-authentication, others may require support interactions, and requests and responses will always be requested in this scenario.
Error Types
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.
For Response-Level and Record-Level error types, an HTTP status code of 200 is returned. For all error types, the HTTP reason phrase should not be evaluated as it is optional and subject to change.
HTTP-Level errors
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 is 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 it is somewhat common when retrieving large batches of records with long individual filter values such as a GUID.
The Identity endpoint can return a 401 Unauthorized error. This is typically due to an invalid Client Id or invalid Client Secret. HTTP-Level Error Codes
Response-Level errors
Response level errors are present when the success
parameter of the response is set to false, and are structured like:
{
"requestId": "e42b#14272d07d78",
"success": false,
"errors": [
{
"code": "601",
"message": "Unauthorized"
}
]
}
Each object in the “errors” array has two members, code
, which is a quoted integer from 601 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 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
An API call that returns this response code is not counted against your daily quota, or your rate limit.
- A date was specified that was not in the correct format
- An invalid dynamic content id was specified
The call cannot be fulfilled because it violates a requirement to create or update an asset, for example, trying to create an email without a template. It is also possible to get this error when trying to:
- Retrieve content for landing pages that contain social content.
- Clone a program that contains certain asset types (see Program Clone for more information).
- Approve an asset that has no draft (that is, has already been approved).
Record-Level record_level_errors
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 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 included in the result array of calls are ordered in the same way as the input array of a request.
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 is present. Each reason contains a “code” member, and a “message” member. The code is always 1xxx, and the message indicates 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 returns a code of 1005, and a message of “Lead already exists” as displayed above.
Record-Level Error Codes
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3 9-row-3 10-row-3 11-row-3 12-row-3 13-row-3 14-row-3 15-row-3 16-row-3 17-row-3 18-row-3 19-row-3 20-row-3 21-row-3 22-row-3 23-row-3 24-row-3 25-row-3 26-row-3 27-row-3 28-row-3 29-row-3 30-row-3 31-row-3 32-row-3 33-row-3 34-row-3 35-row-3 36-row-3 37-row-3 html-authored no-header | ||
---|---|---|
Response Code | Description | Comment |
1001 | Invalid value ‘%s'. Required of type ‘%s' | Error is generated whenever a parameter value has a type mismatch. For example the string value specified for an integer parameter. |
1002 | Missing value for the required parameter ‘%s' | Error is generated when a 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 a 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) |
1012 | Invalid cookie value ‘%s' | Can occur when calling the Associate Lead with an invalid value for the `cookie` parameter. This also occurs when calling Get Leads by Filter Type with `filterType=cookies` and an invalid value for the `filterValues` parameter. |
1013 | Object not found | Get object (list, campaign) by id returns this error code |
1014 | Failed to create Object | Failed to create Object (list) |
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 | Too many clones to program | The subscription has reached the allotted use of `cloneToProgramName` in the 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 |
1025 | Program status not found | A status was specified to Change Lead Program Status that did not match a status available for the program's channel. |
1026 | Custom object not enabled | The action could not be carried out, because the instance does not have custom objects integration enabled. |
1027 | Max Activity Type Limit Reached | The subscription has reached the maximum number of available custom activity types. |
1028 | Max field limit reached | Custom activities have a maximum of 20 secondary attributes. |
1029 |
|
|
1035 | Unsupported filter type | In some subscriptions, the following Bulk Lead Extract filter types are not supported: updatedAt, smartListId, smartListName. |
1036 | Duplicate object found in input | A call was made to update two or more records using the same foreign key. For example, a Sync Companies call using the same externalCompanyId for more than one company. |
1037 | Lead was skipped | The Lead was skipped because it is already in or past this status. |
1042 | Invalid runAt date | The runAt date specified for Schedule Campaign was too far into the future (the maximum is 2 years). |
1048 | Custom Object Discard Draft Failed | A call was made to discard the draft version of a custom object. |
1049 | Failed to Create Activity | Attributes array too long. The array of attributes passed to the record exceeded the max length of 65536 bytes |
1076 | Merge Leads call with mergeInCRM flag is 4. | You are creating a duplicate record. It is recommended that you use an existing record instead. This is the error msg, which Marketo receives when merging in Salesforce. |
1077 | Merge Leads call failed due to `SFDC Field` length | A Merge Leads call with mergeInCRM set to true failed due to `SFDC Field` exceeding the limit of allowed characters. To correct, reduce the length of `SFDC Field`, or set mergeInCRM to false. |
1078 | Merge Leads call failed due to deleted entity, not a lead/contact, or field filter criteria doesn't match. | Merge failure, unable to perform merge operation in natively synced CRM This is the error msg, which Marketo receives when merging in Salesforce. |
1079 | Merge Leads call failed due to Personalized URL conflict in duplicate records | A Merge Leads call specified many Leads with the same Personalized URL. To resolve use Marketo Engage user interface to merge these records. |