Skip to content
Optima docs
Reference

Errors

The response envelope, the status codes the APIs return, and what the common error messages mean and how to fix them.

When a call fails, Optima answers with an HTTP status code and a small JSON body. This page explains the shape of that body, what each status means, and the messages you are most likely to see.

The response envelope

Every response from the CDP and Campaign APIs uses the same envelope.

On success:

{
  "status": "ok",
  "message": "entity created",
  "data": { "...": "..." }
}

On failure:

{
  "status": "error",
  "message": "entity 'customer' already exists"
}
FieldMeaning
statusok or error.
messageA short explanation, written as a sentence that keeps its own case (a header name such as X-Request-ID appears as it is spelt). Show it to a developer; do not match on its exact wording in code. Match on the HTTP status and, where one is given, on data.reason or data.code.
dataThe result on success. On some errors, a structured detail such as the reason for a refusal (see below).
warningsOn a successful write, a list of fields that a data contract flagged at warn level (field, rule, actual_value, level). The request was accepted.
pageOn list responses: page (starting at 0), size (at most 100) and total.

The tracking endpoints used by the SDKs answer with a smaller body, {"status": "error", "message": "…"}. Server errors from those endpoints never include internal detail.

Status codes

StatusMeaningTypical cause and fix
200, 201Done.
202Accepted for processing.Tracking calls. Acceptance means the data is queued; it may not be readable yet.
400The request is malformed or invalid.A field is missing or of the wrong type, a value is out of range, an id is not valid, a batch is too large, or the X-Request-ID header is missing. The message names the problem.
401You are not authenticated.Message unauthorized. The API key or session token is missing, wrong or expired. Send X-APIKey, or Authorization: Bearer …, and sign in again if the session ended.
403You are authenticated but not allowed.Message forbidden: your role does not include this route. Other 403 causes carry their own message and sometimes data.reason; see below.
404Not found.The id, name or route does not exist, or is not visible to you.
409Conflict.The thing already exists (a duplicate name, key or identifier), or a stored credential must be re-entered (see below).
413Request body too large.Send smaller batches.
422Valid shape, but refused by your data rules.A strict schema rejected an undeclared attribute, or a data contract rejected a value.
429Too many requests, or a quota is used up.Wait the number of seconds in the Retry-After header, then retry. See Limits.
500A fault on the Optima side.Retry once; if it persists, give support the X-Request-ID you sent.
503Temporarily unavailable.Retry after the Retry-After header, if present. The CDP and Campaign APIs also answer 503 authentication service unavailable when they cannot reach the credential or session store; the key or session is not at fault, so retry rather than sign in again. For tracking calls the SDKs keep the data and retry for you.

Required headers

Every call to the CDP API must carry an X-Request-ID header with a unique value per request. Without it the call fails with 400 and the message X-Request-ID header is required. Log the value you sent: it is the quickest way for support to find a call.

Authentication uses one of:

  • X-APIKey: <key>, for an application.
  • Authorization: Bearer <token>, for a person's session.

Calls on personal data can also carry X-Purpose, the purpose you are processing the data for (for example marketing, or marketing,analytics).

403 in detail

A 403 has several causes. The message and data tell them apart.

Message or data.reasonMeaningWhat to do
forbiddenThe role of your key or user does not allow this route.Ask a tenant administrator for the role the screen or endpoint needs. See Licences and roles.
tenant suspendedThe environment is suspended.Ask your account administrator.
data.reason is feature_not_licensedYour account's licence does not include the feature. data.feature names it and data.package names the package that includes it. data.package_licensed is true when your account already holds that package, so the feature was switched off or excluded rather than missing.Ask your account owner about the package, or use a different feature.
data.reason is pii_levelThe data you asked for is more sensitive than your clearance allows. data.field names the first field (for example profile.email).Use a key or user with a higher PII level, or drop that field from the request.
data.reason is purpose_not_declaredThe field is tagged with purposes and your call declared none that overlaps.Send an X-Purpose header that covers the data.
data.reason is purpose_not_grantedThe purposes you declared are not granted to your key or user.Ask for the purpose to be granted to the key.
data.reason is signal_purposeA signal or cohort uses data from a purpose you do not hold.As above.
data.reason is purpose_requiredChoose an acting purpose (X-Purpose): the workspace runs in strict mode and every personal-data call must declare one. The message reads X-Purpose header is required in strict mode; match it case-insensitively, as the casing of API messages may change. Prefer the data.reason value.Add X-Purpose.
caller not authorized for purpose: marketingYou declared a purpose that you may not use.Remove it or ask for it to be granted.
X-On-Behalf-Of must be the user's email addressThe on-behalf-of header carried a user id, a name with an address, or anything other than a plain email.Send the user's plain email address.
delegated user is not a member of this tenant, application is not permitted to act on behalf of users and similarA call made on behalf of another user or application is not allowed.Check the delegation settings of the key.
A message beginning only a tenant administrator may… or cannot grant…, cannot raise…You tried to give out more access than you hold.Ask someone with the access to make the change.

Saved reports, segments and metrics are checked against what they use now, not only when they were saved, so a definition can start to be refused after its data's classification changes.

409: credentials must be re-entered

When you change where a stored secret would be sent (a host, URL or type of a connector, provider or similar) without supplying the secret again, the call is refused so the old secret is never sent to a new place. The body is:

{
  "status": "error",
  "message": "credentials must be re-entered when the destination changes",
  "data": { "code": "credentials_required", "fields": ["api_host"] }
}

fields lists the parts of the destination that changed. Repeat the request and include the credential, or clear the stored one explicitly.

422: your data rules

Two kinds of data rules answer with 422.

Strict schema. An entity or event type marked Strict (reject unknown attributes) refuses a write that carries an undeclared attribute:

strict mode violation: attribute 'nickname' is not declared in the schema (strict mode)
strict mode violation in event_type 'purchase': attribute 'coupon' is not declared in the schema (strict mode)

The first form is for a profile write and the second for an event; the event type's name is shown as it was sent.

Data contract. A contract with reject actions refuses a value. The message lists each field and the rule it broke:

data contract violation: email: format; age: max

The rule names are required, type_mismatch, unknown_attribute, format, enum, min, max, min_length, max_length, validate_expr and expr_budget. A contract set to warn does not refuse; it returns the same details under warnings.

400: values that do not fit

A value that does not match the declared attribute type is refused with 400 and a message that names the attribute and what was expected:

attribute 'age': expected number for integer, got string
attribute 'signup_date': cannot parse "tomorrow" as datetime

In a batch call the message starts with the item's position, such as profiles[3]:. Nothing from the batch is stored.

A write that collects an attribute for a purpose you did not declare is refused with a message that names the attributes and the purposes they need (purpose collection violation: attribute(s) ... need one of the purposes [...]) and a list under data.violations, each with the attribute, its attribute_purposes and your declared_purposes.

A schedule that can never occur is refused with 400 (or 422 on a journey trigger), and the message names the cron problem:

schedule_cron: cron: expression never occurs: no selected month has day 30

Choose a day that exists in the month, or add a weekday. See Schedules.

Errors when you save content

Templates and expressions are checked when you save, and the error message tells you where.

MessageMeaning
channel "sms" field "body": template: body:1: unclosed actionA tag is missing its closing braces.
… function "nosuch" not definedA helper name is misspelt or not available in this field. On-site and in-app content has no helpers.
… {{range}} nested deeper than 3 levels is not allowedToo many loops inside loops.
… range over a numeric literal is not allowedA loop over a fixed value; loop over a list instead.
invalid operation: string + intAn expression adds text and a number.
expression nests predicate functions … deep; the limit is 2List functions nested too deeply in an expression.

See Personalization syntax, Template helpers and Expressions.

Tracking endpoints (SDKs)

The public tracking endpoints use a few extra conventions:

StatusMeaning
202The hits were accepted. The body can list hits that were dropped, each with a reason: unknown_category, duplicate or missing_consent. A dropped hit is not an error.
400A request that breaks a hard cap or shape rule (too many properties, a bad device_id, an unknown field).
403The key is not allowed from this origin, the client is blocked, or the feature is not on the account's licence. The answer deliberately does not say which.
404Not found, with the same answer for every reason.
413Body too large or too many hits in one request. The SDKs halve the batch and retry.
429Rate limited. Retry-After gives the wait in seconds.
503Not queued. Retry-After gives the wait; the SDKs keep the data and retry.

On this page