Errors

Every error looks like this:

{
  "error": {
    "code": "invalid_request",
    "message": "The request did not validate. See details.",
    "details": [{ "path": "start_date", "message": "Use YYYY-MM-DD." }]
  },
  "request_id": "8c1f2d3e4a5b6c7d-LHR"
}

Switch on error.code, which is stable. message is written for people and may change. Include request_id when you contact support.

Status	Code	Meaning
400	`invalid_json`	The body is not valid JSON.
400	`invalid_cursor`	The cursor is malformed or belongs to a different query. Start again without one.
400	`api_key_in_url`	A key was sent in the URL. Revoke it.
401	`invalid_api_key`	Missing, invalid, revoked or expired key.
403	`plan_required`	The organization is not on a live Enterprise plan.
403	`insufficient_permission`	A read-only key called a write endpoint.
404	`not_found`	No such endpoint, or no such site in your organization.
409	`site_not_set_up`	The site has no brand profile yet; finish setup in the dashboard.
413	`payload_too_large`	Body over 256 KB.
415	`unsupported_media_type`	Send `Content-Type: application/json`.
422	`invalid_request`	Validation failed; `details` lists each problem. Unknown fields are refused.
422	`invalid_filter`	The filter names a field this endpoint doesn’t have, nests too deep, or misuses an operator.
422	`invalid_sort`	`sort.field` is not one of the requested `group_by` fields or `metrics`.
422	`invalid_date_range`	The range is reversed or too long.
422	`invalid_timezone`	Not an IANA time zone.
422	`prompt_limit_reached`	The change would exceed your plan’s active-prompt limit. `details` has `limit`, `active` and `remaining`.
429	`rate_limited`	Slow down; see Rate limits.
500	`internal_error`	Our fault. It has been reported; retry with backoff.

Retry 429 and 5xx with exponential backoff. Don’t retry other 4xx without changing the request.

Get started

Discovery

Prompts

Reports

Agent Analytics

Action Center