Errors

Error response format

All errors return JSON with at minimum a message field:

{
  "message": "Brand not found",
  "code": "not_found"
}

Some errors include additional context fields (see per-endpoint docs).

Status codes

Code	Meaning	Common causes
`200`	OK	Request succeeded.
`201`	Created	Resource was created (write endpoints).
`400`	Bad Request	Missing or invalid request body / parameters.
`401`	Unauthorized	Missing or invalid API key.
`403`	Forbidden	Feature disabled for your plan or organization.
`404`	Not Found	Brand, run, topic, or prompt doesn’t exist — or doesn’t belong to your organization.
`405`	Method Not Allowed	HTTP method is not supported on this path.
`409`	Conflict	Prompt limit exceeded. Response includes `code: "prompt_limit_exceeded"` and remaining slot counts.
`429`	Too Many Requests	Rate limit exceeded. Back off and retry.
`500`	Internal Server Error	Unexpected server-side failure. Server logs are tagged `[org-api]`.

404 — unknown path

When the path doesn’t match any route, the API returns a helpful 404 with the normalized path and the full list of available endpoints:

{
  "message": "Endpoint not found",
  "path": "/v1/brandz",
  "availableEndpoints": [
    { "method": "GET", "path": "/v1/brands" },
    { "method": "GET", "path": "/v1/brands/{brandId}/runs" }
  ]
}

409 — prompt limit exceeded

{
  "message": "Prompt limit exceeded",
  "code": "prompt_limit_exceeded",
  "remainingSlots": 0,
  "promptLimit": 100,
  "orgWideLimit": 500,
  "orgTotalPrompts": 500
}

403 — feature disabled

{
  "message": "Custom perception prompts are not enabled for this organization",
  "code": "custom_perception_prompts_disabled"
}

Get Started

API Reference

Error response format

Status codes

404 — unknown path

409 — prompt limit exceeded

403 — feature disabled

​Error response format

​Status codes

​404 — unknown path

​409 — prompt limit exceeded

​403 — feature disabled

Error response format

Status codes

404 — unknown path

409 — prompt limit exceeded

403 — feature disabled