Errors and rate limits

Errors from the REST API are JSON: {"detail": "…"}, with a message written to be shown to a person.

Status	Meaning	What to do
401	Missing, invalid or revoked API key — or the organization is suspended or scheduled for deletion	Check the key; create a new one if it was revoked
402	A plan limit refuses the action; the body adds limit, used and allowed	Delete something, wait for the 24-hour window, or upgrade. See Plans and limits
404	No such document in this key’s namespace	Ids are per namespace
409	Identical content already exists as another document in the namespace	Edit that document instead
413	Request over 20 MB, or document text over your plan’s size limit	Split the document
415	Unsupported file type	Use .md, .txt, .pdf or .docx
422	Unreadable file (scanned PDF without text, password-protected, corrupt) or invalid request	The message says which
429	Rate limit: 600 requests per minute per key, MCP and REST together	Wait for the Retry-After seconds

MCP tool calls report problems in their text output (No such section., an ambiguous id) rather than as HTTP errors; an invalid key fails the MCP connection with 401.