Skip to content

Error Handling & Formats

Every failed request to the Portal API returns the same JSON error envelope, so your integration can handle all errors with a single parser. Each response contains a machine-readable code, a human-readable message, and — for validation failures — a details array identifying the exact fields to correct.


{
"error": {
"code": "BAD_REQUEST",
"message": "Bad Request",
"details": [
{
"field": "line_items",
"code": "MAX_ITEMS",
"message": "value must contain no more than 3000 item(s)",
"params": {
"max": "3000"
}
}
]
}
}
Field Type Description
error.code string Machine-readable error identifier (e.g. BAD_REQUEST, UNAUTHORIZED, NOT_FOUND, INTERNAL).
error.message string Human-readable summary of the error condition.
error.details array Optional list of field-level or business-rule violations.

When a request fails validation, each entry in error.details describes a single rejected field:

Field Type Description
field string JSON path to the rejected attribute (e.g. line_items[0].name, line_items[0].end_date, id).
code string Machine-readable rule violation code (e.g. REQUIRED, MIN_LEN, MAX_ITEMS, GT_NOW, MAX_DURATION).
message string Human-readable explanation of why the value was rejected.
params object Key-value pairs describing the rule parameters (e.g. {"min": "3", "max": "255"}).

HTTP Status Error Code Description
400 Bad Request BAD_REQUEST The request payload failed validation or violated a business rule.
401 Unauthorized UNAUTHORIZED The API key is missing, malformed, or inactive.
404 Not Found NOT_FOUND The requested resource does not exist or is not owned by your account.
500 Internal Server Error INTERNAL An unexpected error occurred on our side.

Returned when request fields or business rules fail validation. Correct the fields listed in details and retry:

{
"error": {
"code": "BAD_REQUEST",
"message": "Bad Request",
"details": [
{
"field": "line_items[0].name",
"code": "MIN_LEN",
"message": "must be at least 3 characters",
"params": {
"min": "3"
}
}
]
}
}

Returned when the Authorization: Bearer <YOUR_PARTNER_API_KEY> header is missing, malformed, or references an inactive API key. Verify your partner API key and retry:

{
"error": {
"code": "UNAUTHORIZED",
"message": "Unauthorized"
}
}

Returned when a request addresses one resource by its ID and the ID does not exist or belongs to another account: GET /line-items/{id}, GET /line-items/campaigns/{id}, PATCH /line-items/campaigns/{id}, GET /creatives/{id}, GET /dynamic-content-optimizations/{id}, GET /targetings/{id} and the campaign reporting endpoints GET /reporting/campaigns/{id}, GET /reporting/campaigns/{id}/series and POST /reporting/campaigns/{id}/export. List your resources to obtain valid IDs:

{
"error": {
"code": "NOT_FOUND",
"message": "Not Found"
}
}

Deletes never answer 404. DELETE /line-items, DELETE /targetings, DELETE /trackings and DELETE /dynamic-content-optimizations are idempotent: an ID that does not exist or belongs to another account is skipped and the call returns 200, so repeating a delete is safe.

Returned when an unexpected error occurs. No internal details are exposed. You may retry the request after a short delay; if the error persists, contact support with the request details:

{
"error": {
"code": "INTERNAL",
"message": "Internal Server Error"
}
}

Code Field Cause
REQUIRED name, line_items, campaign_id (on PUT /line-items), start_date, end_date, budget, budget.amount, budget.currency A mandatory field was omitted, set to null or, for an array such as line_items, left empty.
MIN_LEN tags items A tag is shorter than the minimum of 3 characters.
NOT_BLANK name, write-path tags items The value contains only whitespace. Names accept 1 to 255 characters and surrounding whitespace is trimmed on write; tags are not trimmed.
MAX_LEN name, description The string is longer than its maximum (255 characters, 1024 for descriptions).
MAX_ITEMS line_items The request contains more than 3,000 items.
UNIQUE tags, creative_ids The array contains duplicate entries.
HEX id, campaign_id The identifier is not a valid 24-character hexadecimal string.
GT_NOW end_date The end date is not in the future.
AFTER_START_DATE end_date The end date is not after the start date, when both dates are set.
MAX_DURATION end_date The end date is more than 90 days after the start date, when both dates are set.
GT_LTE budget.amount The budget is negative, above 1,000,000,000,000, Infinity or NaN (a budget of 0 is reported as REQUIRED).
DEFINED_ONLY budget.currency The currency is a numeric ID that matches no known currency. An unrecognised currency name is read as unset: REQUIRED.
CURRENCY_CONVERTIBLE budget.currency The currency has no published exchange rate.
GTE line_items[0] The budget is below the 10 USD equivalent minimum (params.min).
LINE_ITEM_BUDGET_BELOW_SPEND line_items[0] The budget is lower than the amount already spent (params.spent_in_usd).
SCHEME creatives[0].source_url The URL scheme is not http or https.
TARGETING_GEO_AREA_NOT_FOUND targetings[0] The geo area does not exist or belongs to another account (params.geo_area_id).
UNSUPPORTED creatives[0].format The format is FORMAT_VAST, which is not supported yet. Use FORMAT_HTML or FORMAT_JSON.

PUT /line-items rejects a line item that points to an object missing from your account. Each unknown reference is reported on line_items[i] with one of these codes: LINE_ITEM_CAMPAIGN_NOT_FOUND (params.campaign_id), LINE_ITEM_PRICING_POLICY_NOT_FOUND (params.pricing_policy_id) and LINE_ITEM_CREATIVE_NOT_FOUND (params.creative_id).

The campaign is checked when a line item is created or moved to another campaign. A stored line item that keeps its campaign is accepted even if that campaign no longer exists.

Pricing policies and creatives are checked first. When one of them is unknown, the response lists only those errors. Field, budget and status checks run once they pass, and campaigns are checked last, so an unknown campaign is reported after the other errors are fixed.