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 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.

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

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.

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 Code	Description	Comment
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.

 

 

Response-Level

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 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 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

* An API call that returns this response code is not counted against your daily quota, or your rate limit

 

Response Code	Description	Comment
502	Bad Gateway	The remote server returned an error. Likely a timeout. The request should be retried with exponential backoff.
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, or Allowlist for IP-Based API Access may be enabled.
604*	Request timed out	The request was running for too long (e.g. encountered database contention), 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 (resets daily at 12:00AM CST). Your quota can be found in your Admin->Web Services menu.  You can increase your quota through your account manager.
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.
616	Invalid subscription type	The appropriate Marketo subscription type is required to access the Custom Object Metadata API.  Please consult your CSM for details.
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. Note: Many failed search operations will return “success = true” and no errors and set a warnings informational string.
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 An invalid dynamic content id was specified
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: 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 (i.e. has already been approved).
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
712	Merge to person Account operation is invalid	A Merge Leads call failed because of an attempt to merge leads that are Salesforce Person Accounts.   Salesforce Person Accounts must be merged in Salesforce.
713	Transient Error	A system resource was temporarily unavailable at the time of the API call.  When this error is encountered, it is advised to wait for a period of time and then retry the request.
714	Unable to find default record type	A Merge Leads call failed because it was unable to find a default record type.
718	ExternalSalesPersonID not found	A Sync Opportunities call was made with a non-existant ExternalSalesPersonID  value.
719	Lock wait timeout exception	A Clone Program call was made and timed out waiting for a lock.

 

Record-Level

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:

Records included in the result array of calls will be 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 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

Response Code	Description	Comment
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’	Can  occur when calling the Associate Lead with an invalid value for cookie parameter. Can also occur when calling Get Leads by Filter Type with filterType=cookies and invalid valid value for filterValues parameter.
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
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	Too many jobs in queue Export daily quota exceeded	Subscriptions are allowed a maximum of 10 bulk extract jobs in the queue at any given time. By default extract jobs are limited to 500MB per day (resets daily at 12:00AM CST).
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.  e.g. a Sync Companies call using the same externalCompanyId for more than one company.
1042	Invalid runAt date	The runAt date specified for Schedule Campaign was too far into the future (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
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 limit of allowed characters. To correct, reduce length of <SFDC Field>, or set mergeInCRM to false.