Errors

The API uses standard HTTP status codes. Errors come back as JSON in this shape:

{
  "detail": "Workspace not accessible by this API key",
  "code": "workspace_forbidden"
}

When validation fails (invalid request body), detail is an array of field-level errors:

{
  "detail": [
    { "loc": ["body", "topics", 0, "name"], "msg": "field required", "type": "missing" }
  ]
}

Status codes

Code	Meaning	What to do
`200 OK`	Success	—
`201 Created`	Resource created	Capture the returned id
`204 No Content`	Success, no body	—
`400 Bad Request`	Malformed request	Fix the request body
`401 Unauthorized`	Missing or invalid credentials	Check `X-API-Key` or `Authorization` header
`403 Forbidden`	Authenticated but not allowed	Add the missing scope, or you’re hitting a workspace you don’t belong to
`404 Not Found`	Resource doesn’t exist	Verify the id
`409 Conflict`	Resource isn’t in the expected state	Check the error code — e.g., `synthesis_pending`
`422 Unprocessable Entity`	Validation error	Fix the field-level issues in `detail`
`429 Too Many Requests`	Rate limited	Honor `Retry-After`
`500 Internal Server Error`	Bug on our side	Retry; if persistent, contact support with the request id
`503 Service Unavailable`	Temporary outage	Retry with backoff

Common error codes

`code`	Meaning
`invalid_api_key`	Key is missing, malformed, or revoked
`insufficient_scope`	Key is missing a required scope
`workspace_forbidden`	Key belongs to a different workspace
`synthesis_pending`	Campaign hasn’t completed synthesis yet
`graph_not_ready`	Entity-extraction pipeline hasn’t finished
`campaign_locked`	Lifecycle action invalid for current status (e.g., starting an already-completed campaign)
`rate_limited`	Per-workspace rate limit exceeded

Idempotency

Safe-by-design endpoints (any GET, DELETE) are naturally idempotent. For POST endpoints, pass an Idempotency-Key header with a unique value (e.g., a UUID) to make retries safe:

Idempotency-Key: 2c4a9cf2-...

The same key replayed within 24 hours returns the original response without creating a duplicate.

Rate limits

Rate limits apply per workspace, not per key. Limits are returned in headers on every response:

Header	Meaning
`X-RateLimit-Limit`	Limit for the current window
`X-RateLimit-Remaining`	Calls remaining in this window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait (only on 429)

Introduction

Endpoints

Status codes

Common error codes

Idempotency

Rate limits

​Status codes

​Common error codes

​Idempotency

​Rate limits

Status codes

Common error codes

Idempotency

Rate limits