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.

{
  "message": "Unauthenticated."
}

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

404 Not Found

Returned when the requested id does not exist for your account.

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. The errors object 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.",
      "The field_name field is required to be string type."
    ]
  }
}

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

Common 422 cases on the write endpoints:

• Audience create - a filter value or project_id that does not exist.
• Activation create - no credentials available (neither caller-supplied nor stored on the connection), an audience below the 500-unique-device minimum to activate, or a prohibited identity field (partner_id, partner_name, pricing_model) in the body. See Activate an Audience.

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.

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

Handling errors

1. Check the HTTP status code first.
2. On 422, iterate errors and surface field-level messages to your user.
3. On 401, refresh the token and retry once.
4. Log message for diagnostics, but branch on status + code.