API Reference
GuidesAPI ReferenceAuthentication

Validations/Error Handling

This page provides information on the Validations and Error Handling for the methods of the Programmatic Deal Open API.

Create Deal Method

MessageReasonRequest Example
Deal type not supported {input deal type}Deal type is not one of the following:

  • DEAL
  • PROGRAMMATIC_GUARANTEED_DEAL
  • FIRST_LOOK_DEAL
  • FIRST_LOOK_DEFER_TO_DIRECT_SOLD_SPONSORSHIPS
  • BIDDABLE_GUARANTEED_DEAL
  • BACKFILL_DEAL
{
"deal_type": "deal",
"name": "test_deal"
}

{
"deal_type": "DEALS",
"name": "test_deal"
}
Deal name is too long (maximum is 255 characters)
Deal description is too long (maximum is 4096 characters)
Deal salesperson is too long (maximum is 255 characters)
Field [field name] is not supported in this method, please check the API documentation for supported fieldsThe Create Deal method only supports four attributes: deal_type, name, description, and salesperson. Any attribute outside of the aforementioned four attributes cannot be used to create a deal.{
"deal_type":"DEAL",
"name":"FW DEAL NAME1",
"description":"FW DEAL DESCRIPTION1",
}

{
"salesperson":"FW DEAL SALESPERSON1"
}

Activate Deal Method

MessageReason
Status can't be changed for an archived deal
Deal Name can't be blank
Public ID can't be blank
At least one activated ad unit must be selected
At least one buyer must be selected
Inventory Assignment must include at least one item
Volume Impression Goal can't be zero.For PG/BG deal, the impression goal can't be 0 when activating the deal.
Impression goals must either have a numerical value or "No Limit" value.If deals except for PG/BG, they must be no limit or have a greater than 0 fixed impression goal.
Schedule end date can't be ongoing.For PG/BG deal, end time should be set when activating the deal.
MRM only supports maximum 25 deals for separate_bid functionality.There are already 25 non-PG deals with:
  • Status is active.
  • The schedule end time is after now.
  • The separate bid request is set to Yes.

Deactivate Deal Method

MessageValidation
Status can't be changed for an archived deal

Deal List Method

ParameterValidationMessage
statusValid values:
  • ACTIVE
  • INACTIVE
  • ARCHIVE
  • PAUSE
  • COMPLETED
Do not support value by: ${param} in filter: status
updated_atIf present, then use this required format:
  • 2017-01-01T14:30:14Z
  • 2017-01-01T14:30:14Z..
  • 2017-01-01T14:30:14Z..2017-01-03T14:30:14Z

Else, ignore this parameter.		updated_at format is invalid.
per_page/pageIf present:

  • The value of per_page and page should be integers.
  • The value of per_page per_page should be no larger than 50.
The pagination is invalid.

Update Deal Method

The two messages below are common validations for updating all fields.

MessageRequest Sample
Unable to update the archived deal
only one field can be updated at once"name": "test deal",
"schedule": {
"start_time": "2021-01-01T00:00",
"time_zone": "(GMT-05:00) America - New York"
}

Validation messages for updatable fields

Name

MessageRequest Sample
Deal name can't be blank when Status is Active
Deal name is too long (maximum is 255 characters)

Description

MessageRequest Sample
Deal description is too long (maximum is 4096 characters)
Invalid request

Salesperson

MessageRequest Sample
Deal salesperson is too long (maximum is 255 characters)
Invalid request

Buyers

MessageValidationRequest Sample
The selected buyers should not include the ones from default seat(blank External Seat ID)For the Programmatic Deal deal, the default seat could not be selected.
All the selected buyers must belong to one buyer platform.For the Programmatic Deal deal, selected buyers should belong to one buyer platform.
It is not possible to remove buyers from an active Programmatic Guaranteed deal.
At least one Buyer must be selected for active Deal.Clear buyers for active deals are not supported.
Invalid request

📘

Note

If there is a non-existent id in the buyer list, it is ignored and other valid buyers are saved in the database.

Ad Units

MessageValidationRequest Sample
At least one active Ad Unit must be selected for active Deal
Invalid ad unit idPotential Reasons:
  1. non-existed ad units
  2. Ad unit's slot type is not PREROLL, MIDROLL, POSTROLL
  3. Ad unit's created type is not SYSTEM_DEFAULT, USER_CUSTOM, SEQUENCED_VARIANT
invalid request

Volume

MessageValidationRequest Sample
no_limit field is required"volume": {
"control_pace": "AS_FAST_AS_POSSIBLE",
"control_period": "DAY",
"impression_goal": 10
}
Volume control period is invalid.control_period is not one of the following:
  • DAY
  • MONTH
  • LIFECYCLE
"volume": {
"no_limit": false,
"control_pace": "AS_FAST_AS_POSSIBLE",
"control_period": "WEEKLY",
"impression_goal": 10
}
Volume control fixed value must be greater than 0 if not no limit.Potential Reasons:
  1. impression_goal < 0
  2. Update active deal with impression_goal = 0
"volume": {
"no_limit": false,
"control_pace": "AS_FAST_AS_POSSIBLE",
"control_period": "WEEKLY",
"impression_goal": -1
}
Invalid excess delivery curveexcess_delivery_curve is not one of the following:
  • NETWORK_DEFAULT
  • 0%
  • 5%
  • 20%
  • 50%
  • 70%

  • UNLIMITED
"volume": {
"no_limit": false,
"control_pace": "AS_FAST_AS_POSSIBLE",
"control_period": "DAY",
"impression_goal": 10,
"excess_delivery_curve": "network_default"
}
Invalid control pacecontrol_pace is not:
  • EVEN
  • AS_FAST_AS_POSSIBLE
"volume": {
"no_limit": false,
"control_pace": "AS_FAST",
"control_period": "DAY",
"impression_goal": 10
}
You can't use "Smooth As" or "Custom" pacing option until you have schedule (Start Date and End Date) specified for this dealSet control_pace to EVEN and control_period to LIFECYCLE for a deal that does not have an end_time
Invalid requestPotential Reason: Impression_goal is not int ."volume": {
"no_limit": false,
"control_pace": "EVEN",
"control_period": "DAY",
"impression_goal": 10.9
}

📘

Note

  • If excess_delivery_curve is set for non-PG/BG deal, the response is 200 but the value will not be saved in DB.

  • For DEAL and BACKFILL_DEAL, the control_pace is set to AS_FAST_AS_POSSIBLE whatever the input is.

Pricing

MessageValidationRequest Sample
Invalid price modelModel is not one of the following:
  • SECOND_FLOOR
  • FIRST_FLOOR
  • FIXED
Price should have (at most) two decimal spaces.Price should not have more than two decimal spaces."pricing": {
"price": 10.011,
"model": "FIXED"
}
price [ - 1 ] must be in the range of 0 and 1000000Potential Reasons:
  1. Price is smaller than 0.
  2. Price is greater than 1,000,000.
"pricing": {
"price": -1,
"model": "FIXED"
}
PG deal [1] only supports fixed price model.Potential Reason:

Set model to SECOND_FLOOR or FIRST_FLOOR for PG deal.
This currency is not supported.The currency is not saved in the FreeWheel system."pricing": {
"price": 10,
"model": "SECOND_FLOOR",
"currency_override": "test"
}

Schedule

MessageValidationRequest Sample
Cannot change the start date because the deal is active.
Start date must be later than 2007-01-01 00:00:00 +0000 UTC.
Guaranteed deals require an End Time.For PG and BG deal, the end_time should be set."schedule": {
"start_time": "2020-12-23T00:00",
"time_zone": "(GMT-05:00) America - New York"
}
End date must be later than current time."schedule": {
"start_time": "2018-12-23T00:00",
"end_time": "2019-12-31T23:59",
"time_zone": "(GMT-05:00) America - New York"
}
First Look deals require an End Time if using Smooth As or Custom pacing.For the First Look deal which has 'Smooth As' volume pace and 'Lifecycle' volume period, the end time could not be cleared.
This time zone is not supported.The timezone is not in the FW system: MRM Timezones
MRM only supports maximum 25 deals for this functionality.There are already 25 non-PG deals with:
  • Status is active.
  • The schedule end time is after now.
  • The separate bid request is set to Yes.
Schedule date format is invalid.Date should be in 2016-01-01T00:00 format.

Max Ad Duration

MessageValidationRequest Sample
Max Ad Duration is not a valid number.max_ad_duration is smaller than -1
Max Ad Duration cannot be applied on Programmatic Guaranteed deal.
Invalid requestPotential Reasons:
  1. max_ad_duration is greater than 2147483647

Buyer Priority Override

MessageValidationRequest Sample
Deal type [type] does not support buyer priority override.Buyer priority override can only. beset for DEAL type deals
Buyer priority override value must be in the range of -1 and 10buyer_priority_override is smaller than -1 or greater than 10
Invalid requestbuyer_priority_override is not int type value

Override

MessageValidationRequest Sample
Deal type [type] does not support ad priority overrideDo not support update override for DEAL and BACKFILL type deals
Ad priority value must be in the range of 11 and 20>For PG and BG deal, when the mode is ABOVE_PAYING_ADS, the value should in [11, 20]"override": {
"mode": "ABOVE_PAYING_ADS",
"value": 8
}
Ad priority value must be in the range of 0 and 100For PG and BG deal, when the mode is AMONGST_PAYING_ADS, the value should in [0, 100]"override": {
"mode": "AMONGST_PAYING_ADS",
"value": 101
}
Ad priority type must be in ABOVE_PAYING_ADS, AMONGST_PAYING_ADSFor PG and BG deal, the mode should be ABOVE_PAYING_ADS or AMONGST_PAYING_ADS"override": {
"value": 15
}
Ad priority value must be in the range of 21 and 30For the First Look deal, the value should in [21, 30]"override": {
"value": 32
}

📘

Note

The input mode for First Look deal is not ignored.

Separate Bid

MessageValidationRequest Sample
MRM only supports maximum 25 deals for this functionality.There are already 25 non-PG deals with:
  • Status is active.
  • The schedule end time is after now.
  • The separate bid request is set to Yes.
PG deals cannot be configured to send separate bid requests (as they do so by default).
Invalid requestSeparate_bid is not bool type.

Creative Approval

MessageReasonRequest Sample
approval_type: must be in the list [NETWORK_DEFAULT, NO_APPROVAL, GLOBAL, CLIENT]"creative_approval": {
"type":"test"
}
clearance_level: cannot be blankclearance_level is required when type is GLOBAL or CLIENT"creative_approval": {
"type":"GLOBAL"
}
clearance_level: must be in the list [PERMISSIBLE, RESTRICTED]"creative_approval": {
"type":"GLOBAL",
"clearance_level":"test"
}

Frequency Cap

MessageValidationRequest Sample
A Deal is allowed to set at most three frequency caps."frequency_caps": {
"items": [
{
"value": 1,
"period": 0,
"type": "TIME"
},
{
"value": 3,
"type": "STREAM"
},s
{
"value": 4,
"type": "ASSET"
},
{
"value": 4,
"type": "LIFETIME"
}
]
}
Frequency Period must be greater than or equal to one."frequency_caps": {
"item": [
{
"value": 1,
"period": 0,
"type": "TIME"
}
]
}
Frequency Type is not supported.Type is not one of the following:
  • TIME
  • STREAM
  • ASSET
  • SITE_SECTION
  • LIFETIME
Frequency Value must be greater than or equal to 0."frequency_caps": {
"items": [
{
"value": -1,
"period": 10,
"type": "TIME"
}
]
}
Frequency caps is inconsistent. Please guarantee the following two conditions: 1) A longer frequency period must have a higher frequency cap. 2) Two frequency caps cannot have the same frequency period."frequency_caps": {
"items": [
{
"value": 100,
"period": 30,
"type": "TIME"
},
{
"value": 5,
"period": 60,
"type": "TIME"
}
]
}

"frequency_caps": {
"items": [
{
"value": 5,
"type": "STREAM"
},
{
"value": 5,
"type": "STREAM"
}
]
}
invalid requestPotential Reasons:
  1. Value is greater than 2147483647.
  2. Period is greater than 2147483647.

Content Targeting

MessageValidationRequest Sample
Inventory Assignment must include at least one itemPotential Reasons:
  1. Clear content targeting for an active deal.
  2. There is no included item when the excluded item is selected.
"content_targeting": {
"exclude": {
"video": [2141954818]
}
}
Content item [214195481811] doesn't exist.Item does not exist in the FreeWheel system"content_targeting": {
"include": {
"video": [11111111]
}
}
item(2141954838) cannot be in both remaining items and sets.The same items cannot be included in sets and in remaining items at the same time."content_targeting": {
"include": {
"sets": [
{
"video": [2141954838],
"relation_in_set": "OR"
}
],
"remaining_items": {
"video": [2141954838]
}
}
}
item(2141954818) cannot be in both include and exclude"content_targeting": {
"include": {
"video": [2141954818]
},
"exclude": {
"video": [2141954818]
}
}
In advanced targeting, the number of sets should be one greater than the number of relations between sets."content_targeting": {
"include": {
"relation_between_sets": [
"OR"
],
"sets": [
{
"video": [2141954849],
"relation_in_set": "OR"
}
],
"remaining_items": {
"video": [2141954838]
}
}
}
Invalid advanced include: the number of sets should not be greater than three."content_targeting": {
"include": {
"relation_between_sets": [
"OR","OR","OR"
],
"sets": [
{
"video": [1],
"relation_in_set": "OR"
},
{
"video": [2],
"relation_in_set": "OR"
},
{
"video": [3],
"relation_in_set": "OR"
},
{
"video": [4],
"relation_in_set": "OR"
}
],
"remaining_items": {
"video": [5]
}
}
}
HyLDA Inventory Assignment can only be updated if ENABLE_HYLDA network function is enabled.Hylda related items could not be selected when ENABLE_HYLDA is not enabled."content_targeting": {
"include": {
"remaining_items": {
"airing": [2141954714],
"relation_in_set": "OR"
}
}
}

Audience Targeting

MessageRequest Sample
item(8) cannot both in remaining items and sets."audience_targeting": {
"include": {
"sets": [
{
"audience_item": [8],
"relation_in_set": "OR"
}
],
"remaining_items": {
"audience_item": [8]
}
}
}
The same item should not be included and excluded."audience_targeting": {
"include": {
"audience_item": [8]
},
"exclude": {
"audience_item": [8]
}
}
In advanced targeting, the number of sets should be one greater than the number of relations between sets"audience_targeting": {
"include": {
"relation_between_sets": [
"OR"
],
"sets": [
{
"audience_item": [4],
"relation_in_set": "OR"
}
],
"remaining_items": {
"audience_item": [8]
}
}
}
Invalid advanced include: the number of sets should not be greater than three."audience_targeting": {
"include": {
"relation_between_sets": [
"OR","OR","OR"
],
"sets": [
{
"audience_item": [
1
],
"relation_in_set": "OR"
},
{
"audience_item": [
2
],
"relation_in_set": "OR"
},
{
"audience_item": [
3
],
"relation_in_set": "OR"
},
{
"audience_item": [
4
],
"relation_in_set": "OR"
}
],
"remaining_items": {
"audience_item": [
8
]
}
}
}
Audience item [1111] doesn't exist."audience_targeting": {
"include": {
"audience_item": [1111]
}
}

Geography Targeting

MessageValidationRequest Sample
item(8) both in include and exclude.The same item should not be included and excluded."geo_targeting": {
"include": {
"country": [
8
]
},
"exclude": {
"country": [
8
]
}
}
item 11111 doesn't exist."geo_targeting": {
"include": {
"country": [
111111
]
}
}
}]]

Platform Targeting

MessageValidationRequest Sample
Platform 111111 doesn't exist."platform_targeting": {
"os": [
111111
]
}

Custom Targeting

MessageValidationRequest Sample
Set number is not matched with relation number."custom_targeting": {
"set": [
{
"key_value": [
"plc=temp",
"zding=test1"
],
"relation_in_set": "OR"
},
{
"key_value": [
"key_3=value_3"
],
"relation_in_set": "OR"
}
],
"relation_between_sets": [
"AND","AND"
]
}
  1. No matter the relation_between_sets elements is AND or OR, always saved it as 'AND' in db.
  2. When there are multi sets for custom targeting, the InSetRelation should always be 'OR'.

Daypart Targeting

MessageValidationRequest Sample
this time zone is not supportedThe timezone is not in the FW system, MRM Timezones

ISP Targeting

MessageValidationRequest Sample
Invalid isp Id 111111"isp_targeting": [
111111
]
Invalid requestisp_targeting should be an int array"isp_targeting": [
"165"
]