Error codes

Every refusal is JSON:

{ "error": "human-readable explanation", "code": "MACHINE_READABLE" }

Switch on code, not on error — the wording may improve, the code will not change meaning.

Some refusals carry extra fields alongside those two: issues on a validation failure, project on a save conflict, balance when credits run out, missing when a bundle names something that does not exist.

Limit and status reasons

These are a closed set. The widget switches on them, and a code it has never seen is a dead end for whoever is reading it, so adding one is a deliberate act that ships with a widget release.

Code	Means	What to do
LIMIT_RUNS	The period’s import runs are used up. Dry runs still work.	Wait for the period to roll over, or upgrade.
LIMIT_ROWS_PER_RUN	The import set is bigger than the plan allows in one run; rowsPerRun says the most.	Split the file, narrow the row range on the Import step, or upgrade.
LIMIT_CONNECTORS	The plan’s connector allowance is used up.	Disconnect one, or upgrade.
LIMIT_ROWS	Server-run imports only: the run would exceed the monthly row allowance.	Wait for the period to roll over, switch on overage if the plan offers it, or upgrade.
LIMIT_MODULES	Enabling this module would exceed the plan’s module limit.	Disable one you are not using, or upgrade.
LIMIT_SCHEDULES	The plan’s schedule limit is reached.	Remove a schedule, or upgrade.
LIMIT_CRM_USERS	Active CRM users exceed the plan’s band.	Upgrade at renewal. This is a warning, never a block — a fifty-seat CRM where two people import is still that CRM’s size.
LIMIT_SANDBOX	The plan’s sandbox allowance is used up.	Detach one, or upgrade.
FEATURE_SHARED_PROJECTS	The plan cannot share projects across the org.	Keep the project private, or upgrade.
FEATURE_HELPER_LIBRARIES	The plan cannot use helper libraries.	Upgrade.
FEATURE_SERVER_RUN	The plan cannot run imports server-side.	Upgrade.
FEATURE_MCP	The plan cannot use the MCP server.	Upgrade.
FEATURE_ROLLBACK	The plan cannot roll a run back.	Upgrade.
FEATURE_SCHEDULED_IMPORTS	The plan cannot schedule imports.	Upgrade.
CREDITS_EXHAUSTED	No AI credits left. The response carries balance.	Buy a credit pack, or wait for the period to roll over.
STATUS_SUSPENDED	The subscription is suspended. Reads still work; writes do not.	Settle the account.
STATUS_PAST_DUE	Payment failed and the grace period is running.	Update the card before the grace period ends.

A 402 always carries the credit balance.

Authentication and authorisation

Code	Status	Means
AUTH_REQUIRED	401	No bearer, or one that does not verify.
TOKEN_REVOKED	401	The API token was revoked.
TOKEN_EXPIRED	401	The API token passed its expiry.
MEMBERSHIP_GONE	401	The bearer is valid but you are no longer a member of the org.
ROLE_REQUIRED	403	Your role is too low. The response names the role needed.
ORG_MISMATCH	403	The bearer was issued for a different org.
SESSION_REQUIRED	403	An API token was used on a session-only route. See Authentication.
ADMIN_REQUIRED	403	A backoffice route without the operator token.
ACCESS_REVOKED	403	An administrator has removed this person’s access to the org. Signing in again does not restore it.
ROLE_CHANGED	403	The role dropped below what this route needs, since the token was issued. Refresh the session.

Validation and conflicts

Code	Status	Means
INVALID_BODY	400	The body did not match the schema. issues carries the list.
BAD_INPUT	400	The same thing, on the AI routes, which use their own code.
UNKNOWN_MODULES	422	A module reference is not in the latest discovery. missing names them.
KEY_CLASH	422	Another module already uses that key or singular name.
NAMESPACE_MISMATCH	422	A helper manifest’s namespace does not match the path it was written to.
EXPIRY_IN_PAST	422	A token expiry that has already passed.
INVALID_PROJECT	422	A project configuration that does not validate. issues carries the list.
PROJECT_CONFLICT	409	Somebody else saved the project first. The response includes their version so you can show the difference rather than overwrite it.
FROM_FUTURE	409	The document was written by a newer build than this server. Stored shapes are migrated forward, never backward.
SANDBOX_ORG	409	A billing action was attempted on a sandbox. Billing lives with the production org.
HAS_SUBSCRIPTION	409	An org with a subscription of its own cannot become a sandbox.
LINK_INVALID	404	A sandbox link code that is unknown, used or expired.

Members

Changing who may do what has its own rules — see People and roles.

Code	Status	Means
SELF_CHANGE	403	You tried to raise your own role, or change your own membership. Lowering your own role is allowed.
OUTRANKED	403	You cannot change somebody above you, or grant a role above your own.
LAST_OWNER	409	The change would leave the org with no owner. Make somebody else an owner first.
MEMBER_NOT_FOUND	404	That person is not in this org.

Discovery

Code	Status	Means
DISCOVERY_FAILED	502	The CRM could not be read. The message says why, bounded to 500 characters.

AI

Code	Status	Means
AI_REFUSED	422	The model declined. category says why.
AI_BAD_OUTPUT	502	The model answered, but not with something usable.
AI_NOT_CONFIGURED	503	AI is not configured on this deployment. Unconfigured paths say so rather than failing obscurely.
ORG_NOT_CONFIGURED	409	The org has no module registry yet. Run discovery and enable a module first.
SESSION_FORBIDDEN	403	That chat session belongs to somebody else.

Not found

404 with a *_NOT_FOUND code — PROJECT_NOT_FOUND, MODULE_NOT_FOUND, FIELD_NOT_FOUND, LIBRARY_NOT_FOUND, SCHEDULE_NOT_FOUND, TOKEN_NOT_FOUND, ORG_NOT_FOUND.

A project you cannot see answers 404 rather than 403, deliberately: whether a private project exists is not something another member should be able to probe for.