Skip to content

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": {
"code": "BAD_REQUEST",
"message": "Bad Request",
"details": [
{
"field": "line_items[0].name",
"code": "NOT_BLANK",
"message": "value must not contain only whitespace"
}
]
}
}
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.

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.

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.

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.

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"
}
]
}
}

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"
}
}

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"
}
}

Returned when the requested resource does not exist or is not accessible to your account:

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

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"
}
}

Returned when the request takes too long to process and is terminated. You may retry the request:

{
"error": {
"code": "TIMEOUT",
"message": "Gateway Timeout"
}
}