Errors and conventions

What the API returns when something is wrong, and what to do about it.

Status codes

Code	Means	Do
200	Done — or an idempotent repeat	Nothing
201	Created	Nothing
400	Your payload	Read detail; do not retry unchanged
401	Key missing, revoked or expired	Check the header, then the console
403	Key lacks the scope, or is not a reseller credential	Mint a key with the scope
404	Not yours, or not there	See below
429	Too fast	Back off and retry
502	A tool server did not answer	Check your MCP endpoint
5xx	Ours	Retry with backoff; tell us if it persists

Errors carry a human-readable detail:

{ "detail": "This API key is missing the \"knowledge:write\" scope." }

404 is deliberately ambiguous

A tenant that belongs to another partner and a tenant that does not exist both return 404. A 403 would confirm the id is real, which would let anyone enumerate a competitor’s customer list one guess at a time. Do not infer existence from the status code.

Retries and idempotency

Tenant provisioning is idempotent on (you, external_ref) — retry it freely after a timeout. Knowledge sync is a full replace, so re-sending the same set converges rather than duplicating.

For everything else, retry 429 and 5xx with exponential backoff. Do not auto-retry a 400.

Async work

Document upload and website crawl return before the work is done. Poll the job before telling a merchant their knowledge is ready.

Versioning

The surface is /api/v1/. Additive changes — new optional fields, new endpoints — can arrive without notice, so parse defensively and ignore fields you do not recognise. Removals and type changes will not happen inside v1 without notice to you first.