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"
}| Field | Meaning |
|---|---|
status | ok or error. |
message | A 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. |
data | The result on success. On some errors, a structured detail such as the reason for a refusal (see below). |
warnings | On a successful write, a list of fields that a data contract flagged at warn level (field, rule, actual_value, level). The request was accepted. |
page | On 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
| Status | Meaning | Typical cause and fix |
|---|---|---|
| 200, 201 | Done. | |
| 202 | Accepted for processing. | Tracking calls. Acceptance means the data is queued; it may not be readable yet. |
| 400 | The 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. |
| 401 | You 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. |
| 403 | You 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. |
| 404 | Not found. | The id, name or route does not exist, or is not visible to you. |
| 409 | Conflict. | The thing already exists (a duplicate name, key or identifier), or a stored credential must be re-entered (see below). |
| 413 | Request body too large. | Send smaller batches. |
| 422 | Valid shape, but refused by your data rules. | A strict schema rejected an undeclared attribute, or a data contract rejected a value. |
| 429 | Too many requests, or a quota is used up. | Wait the number of seconds in the Retry-After header, then retry. See Limits. |
| 500 | A fault on the Optima side. | Retry once; if it persists, give support the X-Request-ID you sent. |
| 503 | Temporarily 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.reason | Meaning | What to do |
|---|---|---|
forbidden | The 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 suspended | The environment is suspended. | Ask your account administrator. |
data.reason is feature_not_licensed | Your 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_level | The 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_declared | The 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_granted | The 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_purpose | A signal or cohort uses data from a purpose you do not hold. | As above. |
data.reason is purpose_required | Choose 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: marketing | You 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 address | The 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 similar | A 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: maxThe 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 datetimeIn 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 30Choose 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.
| Message | Meaning |
|---|---|
channel "sms" field "body": template: body:1: unclosed action | A tag is missing its closing braces. |
… function "nosuch" not defined | A 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 allowed | Too many loops inside loops. |
… range over a numeric literal is not allowed | A loop over a fixed value; loop over a list instead. |
invalid operation: string + int | An expression adds text and a number. |
expression nests predicate functions … deep; the limit is 2 | List 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:
| Status | Meaning |
|---|---|
| 202 | The 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. |
| 400 | A request that breaks a hard cap or shape rule (too many properties, a bad device_id, an unknown field). |
| 403 | The 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. |
| 404 | Not found, with the same answer for every reason. |
| 413 | Body too large or too many hits in one request. The SDKs halve the batch and retry. |
| 429 | Rate limited. Retry-After gives the wait in seconds. |
| 503 | Not queued. Retry-After gives the wait; the SDKs keep the data and retry. |