Updated Marketing API Error Responses

Article
09/20/2024

Warning

Deprecation Notice
The Marketing Version 202310 (Marketing October 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details. If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.

Overview

To make error messages more actionable, we have introduced a standardized error response schema that includes:

New error response fields: errorDetailType and errorDetails
Standard HTTP status codes that will be specific to the error
Updated messages which are clear, actionable, and structured

Note

These updates are available for adCampaignGroups, adCampaigns and adAccounts endpoints only.

By providing a machine-readable error response schema, you will know exactly how to troubleshoot and be able to programmatically fix the error. These changes should make it easier for you to debug effectively on your own.

Changes in Error Response

Sample of Old Error Response

{
    "message": "Validation failed because [{reason=FIELD_VALUE_CONDITIONAL_TOO_LOW, field=totalBudget, type=INVALID_VALUE, message=/totalBudget/amount cannot be set to 10; it cannot be lower than /dailyBudget/amount 50, parameters={field1=/totalBudget/amount, value2=50, value1=10, field2=/dailyBudget/amount, key=348989835}}]",
    "serviceErrorCode": 10007,
    "status": 400,
}

Old Error Response Schema

Field	Type	Description
message	string	A description of the error.
serviceErrorCode	int	A subcode that further classifies the error.
status	int	The HTTP status code.

Sample of New Error Response

{
    "message": "/Campaign/totalBudget/amount cannot be set to 10; it cannot be lower than /Campaign/dailyBudget/amount 50",
    "serviceErrorCode": 10007,
    "status": 400,
    "code": "CONDITIONAL_VALUE_TOO_LOW",
    "errorDetailType": "com.linkedin.common.error.BadRequest",
    "errorDetails": {
        "conditionalInputErrors": [
            {
                "input": {
                    "value": {
                        "decimalValue": "10"
                    },
                    "inputPath": {
                        "fieldPath": "/Campaign/totalBudget/amount"
                    }
                },
                "minValue": "50",
                "code": "CONDITIONAL_VALUE_TOO_LOW",
                "description": "/Campaign/totalBudget/amount cannot be set to 10; it cannot be lower than /Campaign/dailyBudget/amount 50",
                "relatedInputs": [
                    {
                        "value": {
                            "decimalValue": "50"
                        },
                        "inputPath": {
                            "fieldPath": "/Campaign/dailyBudget/amount"
                        }
                    }
                ]
            }
        ]
    }
}

New Error Response Schema

Field	Type	Description
message	string	A description of the error.
serviceErrorCode	int	A subcode that further classifies the error.
status	int	The HTTP status code.
errorDetails	JSON object	Additional error details. Please see this section for schema. This field may be absent in certain cases.
errorDetailType	string	Name of the schema for error detail. `com.linkedin.common.error.BadRequest` is the only available type in this release and more will be added in the future. This field may be absent in certain cases.
code	string	The constant error code that defines the category of the error. Please see this section for all possible error codes.

Note: If you're getting code in the response, it means you're getting the new error response.

ErrorDetails Schema

com.linkedin.common.error.BadRequest schema

Field	Type	Description
inputErrors	InputError[]	Input validation failures for the request query parameters and request body.
conditionalInputErrors	ConditionalInputError[]	Conditional input validation failures for the request query parameters and request body.

InputError Schema

For examples of errors, please see this section

Field	Type	Description
code	string	The error code, e.g. FIELD_VALUE_TOO_LOW.
input	Input	The input in user request causing the error.
key	optional string	The key or an index of an entity in the request for batch operations.
allowedType	optional string	The type that is allowed for the input field.
description	string	An explanation of why the query parameters in the request are bad.
minLength	optional int	The minimum length that is allowed for the input field.
maxLength	optional int	The maximum length that is allowed for the input field.
encoding	optional string	String encoding that is used for the input field.
minValue	optional BigDecimal	The minimum value that is allowed for an input field.
maxValue	optional BigDecimal	The maximum value that is allowed for an input field.
regex	optional string	The regular expression pattern that input must match.

ConditionalInputError Schema

ConditionalInputError has all fields in InputError, along with the below field.

Field	Type	Description
relatedInputs	Input[]	Other inputs that cause the error when combined with the “input” field.

Input Schema

Field	Type	Description
inputPath	oneOf [fieldPath: string, parameterPath: string]	`fieldPath`: a path to the field that caused the error e.g. `/Campaign/runSchedule/start`. `parameterPath`: a path to the parameter within a field that caused the error e.g. `/Campaign/targetingCriteria/include urn:li:adTargetingFacet:locations`
value	optional oneOf [decimalValue: BigDecimal, stringValue: string, booleanValue:boolean]	`decimalValue`: the provided value with type `BigDecimal` in client request for "inputPath" `stringValue`: the provided value with type `string` in client request for "inputPath" `booleanValue`: the provided value with type `boolean` in client request for "inputPath"

Http Status Code Changes

Old Error Message	Old Http Status Code	New Error Message	New Http Status Code
Viewer may not have permission {permission} on entity {entity}	400	Viewer may not have permission {permission} on entity {entity}	403
Viewer may not have permission on field {field}	400	Viewer may not have permission on {field}	403
Viewer may not change {field} on {key} from {oldValue} to {newValue}	400	Viewer may not have permission to change {field} on {entity} from {oldValue} to {newValue}	403
Cannot fetch audience size for the given targetingCriteria field.	400	Cannot fetch audience size for the given targeting criteria field	500
Cannot fetch segment information for the given targetingFacets field.	400	Cannot fetch segment information for the given targeting facets field	500

Error Codes

Below is a list of all possible error codes along with the Http status code and message templates that could be present in the response.

General Errors

Code	HTTP Status Code	Error Message Template
ACTION_NOT_ALLOWED_FOR_CANCELLED_STATUS	400	Action {action} not allowed for cancelled campaigns
AUDIENCE_SIZE_TOO_SMALL	400	The calculated audience size is too small for the given targeting. A minimum audience size of {minValue} is needed
BILLING_NOT_EDITABLE_FOR_LMS_ENTERPRISE	400	{field} is not editable for LMS Enterprise accounts
CAMPAIGN_GROUP_CREATION_NOT_ALLOWED	400	Campaign Group creation is not allowed for Enterprise accounts
CANNOT_UPDATE_BACKFILLED_CAMPAIGN_GROUPS	400	Backfilled campaign groups cannot be updated
CONDITIONAL_FIELD_NOT_ALLOWED	400	{field1} is not allowed when field {field2} is set to {value2}
CONDITIONAL_INVALID_VALUE	400	{field1} cannot be set to {value1} if {field2} is set to {value2}
CONDITIONAL_MISSING_FIELD	400	{field1} is required if {field2} is set to {value2}
CONDITIONAL_VALUE_TOO_HIGH	400	{field1} cannot be set to {value1}; it cannot be higher than {field2} {value2}
CONDITIONAL_VALUE_TOO_LOW	400	{field1} cannot be set to {value1}; it cannot be lower than {field2} {value2}
CONVERSION_CAMPAIGN_MISSING_ASSOCIATED_CONVERSION	400	Campaign being optimized for conversion should have at least one valid conversion associated with it
CREATE_NOT_ALLOWED_WITH_FAILED_CREATIVES	400	Campaign creation is not allowed with creatives in failed state
DATE_IMMUTABLE_WHEN_PASSED	400	{field} cannot be updated when it has already passed
DATE_TOO_EARLY	400	{field} value {value} must be no earlier than {date}
DELETE_ALLOWED_ONLY_FOR_DRAFT_STATUS	400	Delete is allowed only in draft state
ENTITY_WITH_SAME_KEY_ALREADY_EXISTS	400	An entity with the same {field} already exists
FAILED_TO_GET_VALID_CAMPAIGN_CONFIGURATION	400	Failed to fetch valid campaign configurations for account {account} and campaign group {campaignGroup}
FAILED_TO_PROCESS_CAMPAIGN_FOR_AUDIENCE_SIZE_ESTIMATION	400	Failed to process campaign for audience size estimation
FAILED_TO_PROCESS_TARGETING_CRITERIA	400	Failed to process campaign for audience size estimation
FAILED_TO_RETRIEVE_AUDIENCE_SIZE	500	Cannot fetch audience size for the given targeting criteria field
FAILED_TO_RETRIEVE_SEGMENTS	500	Cannot fetch segment information for the given targeting facets field
FAILED_TO_SETUP_ACCOUNT_REPORTING	500	Cannot create account because of internal error in setting up reporting during the creation process
FAILED_TO_VALIDATE_AGAINST_ALLOWED_CAMPAIGN_TYPES	400	Failed to validate against allowed campaign type(s) for account {account}
FIELD_CANNOT_BE_BOTH_IN_INCLUDED_AND_EXCLUDED_TARGETING	400	Cannot have {field} in both included and excluded targeting
FIELD_IMMUTABLE_FOR_NON_DRAFT_CAMPAIGNS	400	{field} cannot be updated unless in draft state
FIELD_LENGTH_TOO_LONG	400	{field} length {length} cannot exceeded maximum {max} length
FIELD_NOT_ALLOWED_FOR_ENTERPRISE_LMS_ACCOUNTS	400	Account {field} must be null for Enterprise LMS accounts
FIELD_NOT_ALLOWED	400	{field} is not allowed to be set
FIELD_VALUE_DOES_NOT_EXIST	400	{field} value {value} does not exist
FIELD_VALUE_NOT_ACTIVE	400	{field} value {value} is not active
FIELD_VALUE_NOT_ALLOWED_FOR_SEGMENT_STATUS	400	{field} field with Ad Segment {adSegmentId} cannot be added to campaign {campaignId} due to invalid segment status value {status}
FIELD_VALUE_TOO_HIGH	400	{field} value {value} cannot be higher than {max}
FIELD_VALUE_TOO_LOW	400	{field} value {value} cannot be lower than {min}
IMMUTABLE_ASSOCIATED_ENTITY	400	Associated entity cannot be changed for talent landing or sponsored update campaigns
IMMUTABLE_CAMPAIGN_FLOOR_PRICE	400	Campaign floor price cannot be updated once set for Sponsored Updates, InMail and Dynamic campaigns
IMMUTABLE_CAMPAIGN_OBJECTIVE_TYPE	400	Campaign objective type cannot be updated once set
IMMUTABLE_CAMPAIGN_TARGETING_AD_ZONES	400	Dynamic Ad Campaigns may not change the size or switch between mobile and non-mobile adzones unless in draft mode
INSUFFICIENT_CAMPAIGN_GROUP_BUDGET	400	The campaign group needs a minimum available budget of {value1}. Currently the remaining campaign group budget is {value2}. Please increase your campaign group total budget to {value3} to meet the minimum amount required to proceed
INVALID_CAMPAIGN_CONFIGURATION	400	ObjectiveType {objectiveType}, CampaignFormat {format}, CampaignType {type}, OptimizationTargetType {optimizationTargetType}, CostType {costType}, OffsiteDeliveryEnabled {offsiteDeliveryEnabled}, audienceExpansionEnabled {audienceExpansionEnabled} is not a valid CampaignConfiguration
INVALID_ENTITLEMENT_FOR_TALENT_LEAD	400	Talent Leads objective cannot be created as account does not have valid entitlement
INVALID_OBJECTIVE_TYPE_WITH_MYNETWORK_DELIVERY	400	Ads with objective type {objectiveType} cannot be served on my network page. The allowed objective types are Engagement and Creative Engagement
INVALID_PAST_ATTRIBUTE_COMBINATION	400	Only one {attributeName} field can be populated except past and current. Past must be inclusive while current is exclusive. {attributeName}sAll: {allValue} {attributeName}sPast: {pastValue} {attributeName}(Current): {currentValue}
INVALID_SEGMENT_ID_AND_FACET_COMBINATION_PROVIDED	400	Audience segment {adSegmentId} does not belong to the facet {value1}. The expected facet is {value2}
INVALID_BILLING_REFERENCE	400	Invalid value {value} for billing reference. Must be a valid urn
INVALID_BILLING_PARENT_REFERENCE	400	Invalid value {value} for billing parent reference. Must be a valid urn
INVALID_VALUE_BLANK_FIELD	400	{field} cannot be blank
INCOMPATIBLE_TARGETING_COMBINATION	400	{field} cannot be set in targeting as it is incompatible with other targeting facets
INVALID_VALUE_DUPLICATE_EXIST	400	{field} value {value} includes duplicates
INVALID_VALUE_FOR_FIELD	400	{field} cannot be set to {value}
MISMATCH_FIELDS	400	Value {value1} of {field1} expected to match value {value2} of {field2}
MISSING_CAMPAIGN_GROUP_ID	400	Campaign creation failed. This account has multiple campaign groups, so a campaign group field must be specified
MISSING_FIELD	400	{field} is required but missing
MISSING_POSITIVE_OPTION	400	The positive option is required for {field} but missing
MULTIPLE_VALIDATIONS_FAILED	400	Multiple errors occurred during the input validation. Please see errorDetails for more information.
MULTIPLE_VALUES_NOT_ALLOWED	400	{field} cannot have multiple values
NONCHARGEABLE_NOT_ALLOWED_UNLESS_ACTIVE_ACCOUNT	400	Cannot create a non chargeable account unless its status is set to ACTIVE
NO_DELETE_ON_LMS_ENTERPRISE_CAMPAIGN_GROUPS	400	Deleting campaign groups in Marketing Solutions enterprise accounts is not allowed. You may change their statuses to Archived instead
NO_PERMISSION_ON_ENTITY	403	Viewer may not have permission {permission} on entity {entity}
NO_PERMISSION_ON_FIELD	403	Viewer may not have permission on {field}
NO_PERMISSION_TO_UPDATE	403	Viewer may not have permission to change {field} on {entity} from {oldValue} to {newValue}
OBJECTIVE_CHANGE_NOT_ALLOWED	400	Objective can only be changed from WEBSITE_TRAFFIC/null to CREATIVE_ENGAGEMENT and vice versa
ONLY_DRAFT_CAMPAIGNS_ALLOWED_IN_DRAFT_CAMPAIGN_GROUPS	400	Only draft campaigns are allowed in draft campaign groups
SPONSORING_LANDING_PAGE_NOT_ALLOWED	400	Sponsoring landing page is allowed only for Enterprise LTS accounts for dynamic or sponsored updates campaigns
START_DATE_AFTER_END_DATE	400	Start date cannot be set to a date after end date
STATUS_CHANGE_NOT_ALLOWED	400	{field} cannot be changed from {beforeValue} to {afterValue}
TARGETING_ADZONE_CHANGE_NOT_ALLOWED	400	{field} cannot contain {values} as dynamic Ad Campaigns may not switch between mobile and non-mobile Ad Zones unless in draft mode
TARGETING_ADZONE_COMBINATION_INVALID	400	Cannot target on both mobile and desktop adZones
TARGETING_FIELD_DEPRECATED	400	Field /targeting is deprecated, please use /targetingCriteria instead
NOT_FOUND	404	Not Found
TIMEOUT	408	Request Timeout
CONFLICT	409	Write Conflict
PRECONDITION_FAILED	412	HTTP precondition header failed
INTERNAL_ERROR	500	Internal Error
NOT_IMPLEMENTED	501	Not Implemented
UNDER_MAINTENANCE	503	Under Maintenance

Account Errors

Code	HTTP Status Code	Error Message Template
BATCH_CREATE_TEST_ACCOUNT_LIMIT_REACHED	400	Batch create request of {count} test accounts failed. Each developer application may have a maximum of {max} test account(s) associated with it.
BLANK_ACCOUNT_NAME	400	Account name cannot be blank.
CURRENCY_MISMATCH	400	The currency {totalBudgetCurrency} of the {totalBudgetField} does not match the currency {accountCurrency} of the account.
CURRENCY_NOT_SUPPORTED	400	The currency {currency} is not supported.
DELETE_NOT_ALLOWED	400	Cannot delete account {id} if the account status is not DRAFT.
INVALID_STATUS_TRANSITION	400	The status cannot be updated to {afterStatus} if the previous status is {beforeStatus}.
MISSING_PRODUCT_TYPE_FOR_ENTERPRISE_ACCOUNT	400	The productType is missing. The productType is required for creating an enterprise account.
TEST_ACCOUNT_LIMIT_REACHED	400	Cannot create another test account. Each developer application may have a maximum of {max} test account(s) associated with it.
UPDATE_REFERENCE_NOT_ALLOWED	400	Reference for personal business and enterprise accounts cannot be updated if the account has campaigns.

Account User Errors

Code	HTTP Status Code	Error Message Template
ACCOUNT_ID_MISMATCH_IN_PARAM_AND_BODY	400	The account id {account_id} in the query parameters does not match the account id {account_id} in the body.
MEMBER_HAD_UNCONFIRMED_EMAIL	400	A confirmed, primary email is required but is not present for account {account}. Please set a primary email and make sure it is confirmed.
MULTIPLE_ACCOUNTS_UNSUPPORTED	400	This request has multiple accounts associated with it, but batch request only supports operations on a single account. Separate the requests by account URN.
USER_MISMATCH_IN_PARAM_AND_BODY	400	The user id {user_id} in the query parameters does not match the user id {user_id} in the body

Examples of New Error Response

Example 1: Error response for single operation `PARTIAL_UPDATE`

This is the error response when trying to set invalid campaign schedule.

{
    "serviceErrorCode": 10007,
    "message": "Multiple errors occurred during the input validation. Please see errorDetails for more information.",
    "status": 400,
    "code": "MULTIPLE_VALIDATIONS_FAILED",
    "errorDetailType": "com.linkedin.common.error.BadRequest",
    "errorDetails": {
        "inputErrors": [
            {
                "input": {
                    "inputPath": {
                        "fieldPath": "/Campaign/runSchedule/start"
                    },
                   "value": {
                       "decimalValue": "1104396800000",
                   }
                },
                "minValue": "1580407874019",
                "code": "DATE_TOO_EARLY",
                "description": "/Campaign/runSchedule/start value 1104396800000 must be no earlier than 1580407874019"
            }
        ],
        "conditionalInputErrors": [
            {
                "input": {
                    "inputPath": {
                        "fieldPath": "/Campaign/runSchedule/end"
                    },
                    "value": {
                       "decimalValue": "1104396800001",
                    }
                },
                "code": "DATE_IMMUTABLE_WHEN_PASSED",
                "description": "/Campaign/runSchedule/end cannot be updated when it has already passed",
                "relatedFields": [
                    {
                        "value": {
                            "stringValue": "COMPLETED"
                        },
                        "inputPath": {
                            "fieldPath": "/Campaign/status"
                        }
                    },
                ]
            }
        ]
    }
}

Example 2: Error response for batch operation `BATCH_PARTIAL_UPDATE`, complete failure

This is the error response when trying to set a budget lower than minimum budget for multiple campaigns.

{
    "results": {},
    "errors": {
        "635137355": {
            "serviceErrorCode": 10007,
            "code": "FIELD_VALUE_TOO_LOW",
            "errorDetailType": "com.linkedin.common.error.BadRequest",
            "message": "/Campaign/totalBudget/amount value 31.0 cannot be lower than 100.00",
            "status": 400,
            "errorDetails": {
                "inputErrors": [
                    {
                        "input": {
                            "value": {
                                "decimalValue": "31.0"
                            },
                            "inputPath": {
                                "fieldPath": "/Campaign/totalBudget/amount"
                            }
                        },
                        "minValue": "100.00",
                        "code": "FIELD_VALUE_TOO_LOW",
                        "description": "/Campaign/totalBudget/amount value 31.0 cannot be lower than 100.00"
                    }
                ]
            }
        },
        "632105125": {
            "serviceErrorCode": 10007,
            "code": "FIELD_VALUE_TOO_LOW",
            "errorDetailType": "com.linkedin.common.error.BadRequest",
            "message": "/Campaign/totalBudget/amount value 31.0 cannot be lower than 100.00",
            "status": 400,
            "errorDetails": {
                "inputErrors": [
                    {
                        "input": {
                            "value": {
                                "decimalValue": "31.0"
                            },
                            "inputPath": {
                                "fieldPath": "/Campaign/totalBudget/amount"
                            }
                        },
                        "minValue": "100.00",
                        "code": "FIELD_VALUE_TOO_LOW",
                        "description": "/Campaign/totalBudget/amount value 31.0 cannot be lower than 100.00"
                    }
                ]
            }
        }
    }
}

Example 3: Error response for batch operation `BATCH_PARTIAL_UPDATE`, partial success

This is the error response when setting low budget for one campaign, but a correct value for the other.

{
    "results": {
        "632105125": {
            "status": 204
        }
    },
    "errors": {
        "635137355": {
            "serviceErrorCode": 10007,
            "code": "FIELD_VALUE_TOO_LOW",
            "errorDetailType": "com.linkedin.common.error.BadRequest",
            "message": "/Campaign/totalBudget/amount value 31.0 cannot be lower than 100.00",
            "status": 400,
            "errorDetails": {
                "inputErrors": [
                    {
                        "input": {
                            "value": {
                                "decimalValue": "31.0"
                            },
                            "inputPath": {
                                "fieldPath": "/Campaign/totalBudget/amount"
                            }
                        },
                        "minValue": "100.00",
                        "code": "FIELD_VALUE_TOO_LOW",
                        "description": "/Campaign/totalBudget/amount value 31.0 cannot be lower than 100.00"
                    }
                ]
            }
        }
    }
}

Share via

Updated Marketing API Error Responses

Overview

Changes in Error Response

Sample of Old Error Response

Old Error Response Schema

Sample of New Error Response

New Error Response Schema

ErrorDetails Schema

InputError Schema

ConditionalInputError Schema

Input Schema

Http Status Code Changes

Error Codes

General Errors

Account Errors

Account User Errors

Examples of New Error Response

Example 1: Error response for single operation `PARTIAL_UPDATE`

Example 2: Error response for batch operation `BATCH_PARTIAL_UPDATE`, complete failure

Example 3: Error response for batch operation `BATCH_PARTIAL_UPDATE`, partial success

Feedback

Additional resources

Share via

Updated Marketing API Error Responses

Overview

Changes in Error Response

Sample of Old Error Response

Old Error Response Schema

Sample of New Error Response

New Error Response Schema

ErrorDetails Schema

InputError Schema

ConditionalInputError Schema

Input Schema

Http Status Code Changes

Error Codes

General Errors

Account Errors

Account User Errors

Examples of New Error Response

Example 1: Error response for single operation PARTIAL_UPDATE

Example 2: Error response for batch operation BATCH_PARTIAL_UPDATE, complete failure

Example 3: Error response for batch operation BATCH_PARTIAL_UPDATE, partial success

Feedback

Additional resources

Example 1: Error response for single operation `PARTIAL_UPDATE`

Example 2: Error response for batch operation `BATCH_PARTIAL_UPDATE`, complete failure

Example 3: Error response for batch operation `BATCH_PARTIAL_UPDATE`, partial success