投放接口错误处理指引

在调用MarketingAPI的过程中，偶尔可能会遇到接口返回系统错误，典型的错误码有30000-30099等。

此类错误的发生原因可能是因为网络波动，导致请求超时，或者底层服务遭遇短暂不可用的故障。遇到此类问题，建议开发者进行接口的重试，一般重试次数控制在1-3次之间。

如果对一些投放接口有幂等的需求，即当前请求的参数只想要创建唯一的一个广告资源，那么可以在请求的时候增加X-Request-Id的请求头，标示本次请求的唯一值，且这个值跟客户自身的请求参数是对应的。

即当请求参数是A时，X-Request-Id为AA时，即使重复请求，API侧永远不会新建一个全新的广告资源，避免重试的时候重复创建。如果在创建时重复传入相同的请求参数和X-Request-Id，那么会返回该X-Request-Id对应的唯一的广告资源。

目前支持X-Request-Id的请求头的有：
"campaigns/add",
"adgroups/add",
"ads/add",
"adcreatives/add",
"dynamic_creatives/add",
"advertiser/add"

在使用的过程中，如果开发者用了相同的X-Request-Id，但是不同的请求参数，那么API会返回31060错误码，错误消息 – “您的请求参数与之前具有相同X-Request-Id的请求不同，请更新参数后重试”。

实际应用场景

请求接口： adgroups/add
请求体：

{
    "account_id":10000001,
    "adgroup_name":"腾讯广告投放2021",
    "automatic_site_enabled":"false",
    "begin_date":"2021-01-01",
    "bid_amount":5000,
    "bid_strategy":"BID_STRATEGY_TARGET_COST",
    "billing_event":"BILLINGEVENT_IMPRESSION",
    "campaign_id":2000001,
    "daily_budget":0,
    "end_date":"2021-12-31",
    "expand_enabled":"false",
    "expand_targeting":[

    ],
    "optimization_goal":"OPTIMIZATIONGOAL_FIRST_PURCHASE",
    "promoted_object_id":"1010101",
    "promoted_object_type":"PROMOTED_OBJECT_TYPE_MINI_GAME_WECHAT",
    "site_set":[
        "SITE_SET_WECHAT"
    ],
    "targeting":{
        "age":[
            {
                "max":66,
                "min":36
            }
        ],
        "game_consumption_level":[
            "HIGH"
        ],
        "gender":[
            "MALE"
        ],
        "geo_location":{
            "location_types":[
                "LIVE_IN"
            ],
            "regions":[
                500000,
                110000
            ]
        },
        "wechat_ad_behavior":{
            "actions":[

            ],
            "excluded_actions":[
                "MINI_GAME_WECHAT_REGISTERED"
            ]
        }
    },
    "time_series":"111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111"
}

返回体：

{
    "code":30021,
    "message":"Delivery service interface error,please contact our dedicated operation team,interface error code: 101 trace_id: 111111-222222-333333-444444",
    "message_cn":"投放服务接口错误，请联系我们的专业运营团队，接口错误码为: 101 trace_id: 111111-222222-333333-444444"
}

此时请求返回是30021（参考范围30000~30099），表示系统遇到不可预见的一些情况，建议重试。但是此时因为没有加X-Request-Id头，所以高并发的重试，可能会让上述相同参数的请求创建多个adgroup出来。X-Request-Id头就是为了解决该问题。

解决后的请求：
请求接口：adgroups/add
请求体：

{
    "account_id":10000001,
    "adgroup_name":"腾讯广告投放2021",
    "automatic_site_enabled":"false",
    "begin_date":"2021-01-01",
    "bid_amount":5000,
    "bid_strategy":"BID_STRATEGY_TARGET_COST",
    "billing_event":"BILLINGEVENT_IMPRESSION",
    "campaign_id":2000001,
    "daily_budget":0,
    "end_date":"2021-12-31",
    "expand_enabled":"false",
    "expand_targeting":[

    ],
    "optimization_goal":"OPTIMIZATIONGOAL_FIRST_PURCHASE",
    "promoted_object_id":"1010101",
    "promoted_object_type":"PROMOTED_OBJECT_TYPE_MINI_GAME_WECHAT",
    "site_set":[
        "SITE_SET_WECHAT"
    ],
    "targeting":{
        "age":[
            {
                "max":66,
                "min":36
            }
        ],
        "game_consumption_level":[
            "HIGH"
        ],
        "gender":[
            "MALE"
        ],
        "geo_location":{
            "location_types":[
                "LIVE_IN"
            ],
            "regions":[
                500000,
                110000
            ]
        },
        "wechat_ad_behavior":{
            "actions":[

            ],
            "excluded_actions":[
                "MINI_GAME_WECHAT_REGISTERED"
            ]
        }
    },
    "time_series":"111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111"
}

请求头：
X-Request-Id:adgroup_001

返回体：

{
    "code":0,
    "data":{
        "adgroup_id":123123123
    },
    "message":"",
    "message_cn":""
}

注意点：

相同的请求体，对应的请求头X-Request-Id应当相同，否则系统会报如下错误，表示相同请求体有不同的X-Request-Id的请求头，不合法。

{
"code":31060,
"message":"Your request differs from a previous request with the same X-Request-Id. trace_id: 123-123-123-123-123-123",
"message_cn":"您的请求参数与之前具有相同X-Request-Id的请求不同，请更新参数后重试 trace_id: 123-123-123-123-123-123"
}

满足上述条件的请求，可以重试请求，请求的返回结果都是该请求参数和X-Request-Id对应的adgroup_id，不会造成相同参数的请求创建多个adgroup的结果。
建议相同请求体跟X-Request-Id保持一一对应的映射关系。

在同一时间，用相同X-Request-Id高并发请求相同的接口，只有一个请求会成功。其他的请求会收到如下返回信息。

{
"code":36019,
"message":"You have multiple concurrent requests with the same X-Request-ID at the same time, and only one of them succeeds. trace_id: a7b4ead4a4fab3ec697cf314d157fa53",
"message_cn":"您在同一时刻具有多个相同X-Request-Id的并发请求，只有一个会请求成功 trace_id: a7b4ead4a4fab3ec697cf314d157fa53"
}

首页

开发文档

最新动态

腾讯广告

投放接口错误处理指引

实际应用场景