Skip to main content
Errors follow a single body shape across the API: 
{
  "status": 409,
  "code": "AGENT_NAME_TAKEN",
  "message": "Agent name already exists in this workspace",
  "timestamp": "2026-05-25T14:30:12.234567Z"
}
FieldNotes
statusEcho of the HTTP status. Always matches the response code.
codeMachine-readable, stable identifier — safe to switch on.
messageHuman-readable explanation. Wording may change; don’t pattern-match.
timestampServer time the error occurred. Useful for support tickets.

​
Status code reference

StatusWhen you’ll see it
200 / 201 / 204Success. 201 for creates, 204 for deletes with no body.
400Validation failed, malformed JSON, unknown fields, invalid pagination, immutable field touched.
401Missing or invalid API key. See Authentication.
403Workspace lacks permission for this operation (e.g. trying to use a feature not in the plan).
404Resource not found. Either the ID doesn’t exist or it belongs to a different workspace.
408Sync agent message timed out — increase timeoutSeconds (max 300) or switch to the streaming endpoint.
409Conflict — duplicate name, resource already linked, state transition not allowed.
422Business rule violation — e.g. plan limit reached, cycle detected, channel config blocked.
429Rate or quota limit hit. Wait and retry.
500Server error. Should not happen — file a bug with the timestamp from the body.
502Upstream service unreachable (the request reached our gateway, but a downstream — Composio, payment provider — failed). Usually transient.

​
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

StatusRetry?
400 / 404 / 409 / 422No. Fix the request.
401No. Fix the key.
408Sometimes. Increase timeoutSeconds or use streaming.
429Yes, with exponential backoff. Start at 1s, cap at 30s.
500 / 502Yes, with exponential backoff. If a 500 persists, it’s a bug — file a report.
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.