Errors

All errors keep the envelope shape with status: "error". The HTTP status code is mirrored in code.

401 Unauthenticated

Returned when the bearer token is missing, invalid, or expired. The token of a deactivated account is invalid.

The credential endpoints (login, and creating or revoking API and MCP tokens) return it when the email and password do not log in: a wrong email or password, or an account that is deactivated or not yet confirmed. Each case gets the same response.

{
  "message": "Unauthenticated."
}

Fix: get a fresh token from POST /api/v2/auth/login and resend the request with Authorization: Bearer <token>.

403 Forbidden

Returned when your account may not make the request. Most often the request uses a gated capability that is not enabled for your account, for example creating a cohort. message says what is missing, and data is empty. The credits endpoints return it to an organization that is not billed in credits, before they validate anything.

{
  "status": "error",
  "code": 403,
  "message": "Cohorts require additional permissions that are not enabled for your account. Contact your Account Manager to enable this feature.",
  "data": []
}

Fix: ask your Account Manager to enable the capability. Resending the same request gets the same answer until it is enabled.

404 Not Found

Returned when the requested id does not exist for your account. Create Activation and Create Schedule also return it for an endpoint connection whose partner is not set up for your company (see Get Endpoint Partners).

406 Not Acceptable

Returned when the request does not send Accept: application/json.

Fix: always send both:

Content-Type: application/json
Accept: application/json

409 Conflict

Returned by a resource-create endpoint when an Idempotency-Key is reused with a different request body, or when a duplicate of a still in-flight create arrives with the same key.

Fix: use a fresh key for a genuinely new create, and reuse a key only to retry the identical request. See Idempotency.

422 Validation error

Returned when the request body fails validation. data.errors maps each invalid field to an array of human-readable messages.

{
  "status": "error",
  "code": 422,
  "message": "Validation error.",
  "data": {
    "errors": {
      "field_name": [
        "The field_name field is required."
      ]
    }
  }
}

Fix: read data.errors, correct the named fields, and retry.

The POI Create Category, Create Brand and Submissions endpoints list the messages in a top-level errors object instead, next to data:

{
  "status": "error",
  "code": 422,
  "message": "Validation error.",
  "data": [],
  "errors": {
    "field_name": [
      "The field_name field is required."
    ]
  }
}

Common 422 cases on the write endpoints:

Audience create and estimate - a filter value or project_id that does not exist, or a dataset your account cannot build. The messages, with the field they are on:
- datasets..type: “The <type> dataset type is not enabled for your account. Contact your Account Manager to enable it.”
- datasets..signal_providers: “These signal providers are not available to your account for the <type> dataset type: <names>. Use the values the signal providers reference read returns for this dataset type.” A provider already used on one of your organization’s audiences of that dataset type is accepted, as long as it is still a signal provider, see Get Signal Providers.
- crossvisitation, analyses.frequency or analyses.apps_frequency: “The <analysis> analysis is not available for this dataset combination.”
- datasets..start_date: “Deidentified data is available from <date>. Choose a later start date.”
- datasets..end_date: “Deidentified signals for the United States are limited to a maximum of 2 weeks per delivery.”
- datasets..type: “Deidentified datasets cannot be combined with another dataset.”
Schedule create - an audience whose first cycle your account cannot build. message starts with “This audience cannot be scheduled:” and goes on with one of the audience messages above, and data.errors.audience_id lists every reason. See Create Schedule.
Activation create - a project_id that does not exist, no credentials available (neither caller-supplied nor stored on the connection), an audience below the 500-unique-device minimum to activate, a pricing_model_id that Get Pricing Models does not list for the connection’s partner and one of the audience’s dataset types (Create Schedule too), or a prohibited identity field (partner_id, partner_name, pricing_model) in the body. See Activate an Audience.
Delivery bucket or folder (Activation create and Schedule create) - a bucket input that names an Intuizi bucket or a path in an Intuizi delivery bucket outside your organization’s delivery folder, a bucket that is not a standard bucket name (a path, an access point alias, or an ARN), or a folder prefix with a quote, a backslash, a control character, or a .. segment. message is “The delivery bucket or folder is not available to your organization.” and data is empty. This message text does not change, so a client can match on it. See Delivery buckets and folders.
Delivery without access keys (Activation create and Schedule create) - a delivery with no access keys or service account key of your own, to a bucket that Intuizi has not registered for your organization or outside the folder registered with it. message is “This delivery has no access keys or service account of your own, so it can only go to a bucket registered for your organization. Add your own access keys or service account, or ask your Account Manager to register the bucket.” and data is empty. This message text does not change, so a client can match on it. See Deliveries without access keys.
Cohort create - a file_uri that is not a source you can use, for example a path in an Intuizi delivery bucket outside your organization’s delivery folder, another Intuizi bucket, or a path with an empty, . or .. segment. data.errors.file_uri says the file cannot be read. See Create Cohort.
Cohort preview - a well-formed file_uri that is not a source you can use, or a file that cannot be read. This answer has no data.errors: message says the file cannot be read, and data is empty. A file_uri that is not an s3:// or gs:// URI with a bucket and a path still gets its message in data.errors.file_uri. See Preview Cohort File.

429 Too Many Requests

Returned when you exceed the per-token rate limit (120 reads/min, 30 writes/min). The response includes a Retry-After value in seconds.

The credential endpoints also return it after too many failed logins for one email: for that email only, whatever the password, until Retry-After has passed.

Create an Upload also returns it when your organization already has 20 open uploads (see Limits & Quotas), and message says so. Retry-After is then the seconds until the first of them expires. A create that uses up one of the open references makes room sooner.

{
  "status": "error",
  "code": 429,
  "message": "Too many requests. Please retry after the time indicated by the Retry-After header.",
  "data": []
}

Fix: wait Retry-After seconds, then retry. On a create, resend the same Idempotency-Key so the retry cannot double-create. After failed logins, check the credentials before you retry. See Polling and Rate Limits.

Handling errors

Check the HTTP status code first.
On 422, iterate data.errors (errors on the POI endpoints above) and surface field-level messages to your user.
On 401, refresh the token and retry once.
On 403, do not retry: show message to your user.
Log message for diagnostics, but branch on status + code.

Status Codes The Async Model