Error Handling
Every failed request to the Gateway 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[0].name", "code": "NOT_BLANK", "message": "value must not contain only whitespace" } ] }}Envelope Fields
Section titled “Envelope Fields”| Field | Type | Description |
|---|---|---|
error.code |
string |
Machine-readable error identifier (e.g. BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, INTERNAL). |
error.message |
string |
Human-readable summary of the error condition (e.g. Bad Request, Unauthorized). |
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). |
code |
string |
Machine-readable rule violation code (e.g. REQUIRED, MIN_LEN, MAX_LEN, NOT_BLANK). |
message |
string |
Human-readable explanation of why the value was rejected. |
params |
object |
Key-value pairs describing the rule parameters (e.g. {"max": "255"}). Rules such as NOT_BLANK have no parameters. |
Names, Tags and Roles
Section titled “Names, Tags and Roles”Campaign, line item, creative and area names accept 1 to 255 characters and must not contain only whitespace
(NOT_BLANK). The character limit applies before trimming. Surrounding whitespace is trimmed on write and responses
return the stored name; internal whitespace is preserved. For example, " A " is stored as "A".
Campaign creation permits an omitted or empty line item name, which defaults to Line item N. Required names instead
return REQUIRED when omitted or empty; supplied whitespace-only names return NOT_BLANK.
Each tag on user, line item, creative and area writes must be 3 to 255 characters and not only whitespace. User-write roles must be 1 to 255 characters and not only whitespace. Role filters accept 1 to 255 characters. Tags and roles are validated as supplied, without trimming; their length and uniqueness constraints still apply.
Status Codes
Section titled “Status Codes”| HTTP Status | Error Code | When it occurs |
|---|---|---|
400 Bad Request |
BAD_REQUEST |
The request payload failed validation or violated a business rule. Check details for the fields to fix. |
401 Unauthorized |
UNAUTHORIZED |
The JWT bearer token is missing, expired, or invalid. |
403 Forbidden |
FORBIDDEN |
The authenticated user’s role does not grant the permission required by the operation. |
404 Not Found |
NOT_FOUND |
The requested resource does not exist or is not accessible to your account. |
409 Conflict |
CONFLICT |
The request conflicts with the current state of the resource (e.g. duplicate identifier or concurrent modification). |
429 Too Many Requests |
TOO_MANY_REQUESTS |
The rate limit for your account has been exceeded. Retry after a short delay. |
500 Internal Server Error |
INTERNAL |
An unexpected error occurred on our side. No internal details are exposed. |
504 Gateway Timeout |
TIMEOUT |
The request took too long to process and was terminated. |
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": "NOT_BLANK", "message": "value must not contain only whitespace" } ] }}401 Unauthorized
Section titled “401 Unauthorized”Returned when the Authorization: Bearer <ACCESS_TOKEN> header is missing, malformed, or references an expired or
invalid token. Obtain a new access token and retry:
{ "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" }}403 Forbidden
Section titled “403 Forbidden”Returned when the authenticated user’s role does not grant the permission required by the operation. Review the User Roles and Permissions to confirm the roles authorized for the operation:
{ "error": { "code": "FORBIDDEN", "message": "Forbidden" }}404 Not Found
Section titled “404 Not Found”Returned when the requested resource does not exist or is not accessible to your account:
{ "error": { "code": "NOT_FOUND", "message": "Not Found" }}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" }}504 Gateway Timeout
Section titled “504 Gateway Timeout”Returned when the request takes too long to process and is terminated. You may retry the request:
{ "error": { "code": "TIMEOUT", "message": "Gateway Timeout" }}