Updated Marketing API Error Responses

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 be available for adCampaignGroupsV2 endpoint and adCampaignsV2 endpoints only.

By providing a machine-readable error response schema, you will know exactly how to troubleshoot and be able to programatically 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 DEPRECATED A subcode that further classifies the error. We recommend you to use code field instead.
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.

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
INCOMPATIBLE_TARGETING_COMBINATION_FOR_APP_TRACKING_TRANSPARENCY 400 Facet {field1} with value(s) {value1} cannot be AND'ed with {field2} to comply with app tracking transparency requirements. Please refer to the API documentation for the list of incompatible combinations.
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

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"
                    }
                ]
            }
        }
    }
}