Errors

​

Error response format

{
  "code": 422,
  "messages": ["Unprocessable: A description of what went wrong"]
}

​

Status codes at a glance

​

Status Code 403 — Unauthorized

{
  "code": 403,
  "messages": ["Unauthorized: Please check your Chameleon Account Secret"]
}

• Verify your X-Account-Secret header value matches a token from Settings → Tokens.
• Check that the token hasn’t been revoked. You can generate a new one from the dashboard.
• Ensure you’re using the Account Secret (not the Account Token, which is for the JavaScript snippet).
• Confirm the header name is exactly X-Account-Secret (case-sensitive).

​

Status Code 404 — Not Found

{
  "code": 404,
  "messages": ["Endpoint not found: Please recheck with the API docs https://developers.chameleon.io"]
}

• Verify the URL was copied correctly. URLs include an environment specifier after the version (e.g., /v3/edit/tours, /v3/analyze/profiles).
• Check that the resource ID exists and belongs to your account.
• Ensure the base URL is https://api.chameleon.io (not a typo or old URL).
• For profile lookups, confirm the uid or email has been previously identified to Chameleon.

​

Status Code 409 — Conflict

{
  "code": 409,
  "messages": ["Conflict: Please check the preconditions in the API docs https://developers.chameleon.io"]
}

• Delivery to unpublished Experience — The Tour or Microsurvey must be published before creating a Delivery. Publish it first via the dashboard or API.
• Updating a triggered Delivery — Once a Delivery has been triggered (at has a value), it can no longer be modified or deleted.
• Too many pending Deliveries — A user has reached the pending Delivery limit (default: 3). Use delivery_ids_at_limit=drop to replace the oldest, or delete existing Deliveries first.
• Import already started — Once import_at is set on an Import, it can’t be updated.
• Search item/group limits exceeded — HelpBar content limits reached. See HelpBar limits.

​

Status Code 422 — Unprocessable

{
  "code": 422,
  "messages": ["Unprocessable: Please check the request parameters with the API docs https://developers.chameleon.io"]
}

• Invalid timestamp — A parameter expected as a timestamp can’t be parsed. Use ISO 8601 format (e.g., "2024-01-15T10:30:00Z").
• Missing identifier — Looking up a User Profile requires at least one of id, uid, or email.
• Invalid filter expression — A segmentation filter has incorrect syntax or unsupported operators.
• Import property mismatch — CSV column headers don’t match the specified properties mapping.
• Invalid enum value — A parameter like kind or model_kind has an unrecognized value.

​

Status Code 429 — Rate Limited

X-Ratelimit-Wait: 114
X-Ratelimit-Limit: 2

{
  "code": 429,
  "messages": ["Rate Limited: Please refer to the API docs https://developers.chameleon.io/concepts/rate-limiting for more information"],
  "wait": 14
}

• Check the wait field in the response body — this tells you how many seconds to wait before retrying.
• Check the X-Ratelimit-Wait header for the wait time in seconds.
• Implement exponential backoff: wait the specified time, then retry with increasing delays if still limited.
• Review your concurrency: the Chameleon API limits concurrent requests per endpoint. See Rate limiting for per-endpoint limits.
• For bulk operations, consider using batch endpoints (e.g., bulk tagging) instead of individual requests.

​

Status Code 500 — Internal Server Error

{
  "code": 500,
  "messages": ["Internal server error: Please retry later"]
}

• This is typically a transient issue. Wait a few seconds and retry.
• If the error persists, check status.chameleon.io for any ongoing incidents.
• If the problem continues after retrying, contact support with the request details and timestamp.

​

Status Code 503 — Service Unavailable

{
  "code": 503,
  "messages": []
}

• This typically indicates maintenance or temporary unavailability. Check status.chameleon.io.
• Implement retry logic with exponential backoff.
• If you see frequent 503 errors, you may be hitting system-wide rate limits. See Rate limiting.

​

Status Code 504 — Gateway Timeout

{
  "code": 504,
  "messages": ["Internal timeout: An internal operation took too long."]
}

• The request may have been too complex (e.g., a broad search query or large filter set). Try narrowing your request.
• Retry after a brief delay. If the issue persists, simplify the request parameters.
• For large dataset operations, use pagination with smaller limit values.