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 Envelope
Section titled “Error Envelope”{ "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" } } ] }}Envelope Fields
Section titled “Envelope Fields”| 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. |
Validation Detail Fields
Section titled “Validation Detail Fields”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"}). |
Status Codes
Section titled “Status Codes”| 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. |
400 Bad Request
Section titled “400 Bad Request”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" } } ] }}401 Unauthorized
Section titled “401 Unauthorized”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" }}404 Not Found
Section titled “404 Not Found”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.
500 Internal Server Error
Section titled “500 Internal Server Error”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" }}Common Validation Error Codes
Section titled “Common Validation Error Codes”| 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. |
Unknown references
Section titled “Unknown references”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.