Skip to main content
Errors follow a single body shape across the API:

​
Status code reference

​
Common error codes

These are the codes you’ll see most often. The full set is documented per endpoint in the API Reference.

​
Authentication

  • MISSING_API_KEY, INVALID_API_KEY_FORMAT, INVALID_API_KEY — all 401.

​
Validation

  • VALIDATION_ERROR — 400. Body has invalid fields, bad enum value, or unknown property.
  • MALFORMED_JSON — 400. Request body isn’t valid JSON.
  • IMMUTABLE_FIELD — 400. Tried to change a field that can’t be edited after creation (e.g. toolType).

​
Resource state

  • AGENT_NOT_FOUND, CLIENT_NOT_FOUND, KNOWLEDGE_SOURCE_NOT_FOUND, etc. — 404.
  • ALREADY_LINKED, AGENT_NAME_TAKEN, SKILL_NAME_TAKEN, EXTERNAL_MCP_NAME_TAKEN — 409.

​
Business rules

  • NO_DRAFT_VERSION — 409. The agent has no draft to modify; publish first or create a new draft.
  • SUB_AGENT_CYCLE — 422. Linking would create a cycle (A → B → A).
  • OAUTH_NOT_SUPPORTED_VIA_API — 422. OAuth registration requires the Studio web flow.
  • CHANNEL_CONFIG_NOT_ALLOWED_VIA_API — 422. WhatsApp config requires Meta OAuth in Studio web.
  • HTTP_TOOL_LIMIT_REACHED — 422. Workspace is at the plan limit.

​
Retry guidance

Idempotent operations (GET, DELETE) are always safe to retry. For POST / PATCH, retry only on transient failures (429, 502, network errors) to avoid double-creates.