Erros

Erros seguem um único shape em toda a API:

{
  "status": 409,
  "code": "AGENT_NAME_TAKEN",
  "message": "Agent name already exists in this workspace",
  "timestamp": "2026-05-25T14:30:12.234567Z"
}

Campo	Notas
`status`	Echo do status HTTP. Sempre bate com o código da resposta.
`code`	Identificador estável e machine-readable — seguro para usar em `switch`.
`message`	Explicação para humanos. A redação pode mudar; não dê match por padrão de texto.
`timestamp`	Horário do servidor quando o erro ocorreu. Útil para tickets de suporte.

Referência de status codes

Status	Quando você vai ver
`200` / `201` / `204`	Sucesso. `201` para create, `204` para delete sem body.
`400`	Validação falhou, JSON malformado, campos desconhecidos, paginação inválida, campo imutável tocado.
`401`	API key ausente ou inválida. Veja Autenticação.
`403`	Workspace sem permissão para esta operação (ex.: tentar usar feature fora do plano).
`404`	Recurso não encontrado. Ou o ID não existe, ou pertence a outro workspace.
`408`	Mensagem síncrona excedeu o timeout — aumente `timeoutSeconds` (max 300) ou use o endpoint de streaming.
`409`	Conflito — nome duplicado, recurso já vinculado, transição de estado não permitida.
`422`	Violação de regra de negócio — ex.: limite do plano, ciclo detectado, configuração de canal bloqueada.
`429`	Limite de rate ou cota. Aguarde e tente de novo.
`500`	Erro de servidor. Não deveria acontecer — abra um bug com o `timestamp` do body.
`502`	Serviço upstream inacessível (a request chegou no gateway, mas um downstream — Composio, payment provider — falhou). Geralmente transiente.

Códigos de erro comuns

Estes são os códigos que você vai ver mais. O conjunto completo está documentado por endpoint na API Reference.

Autenticação

MISSING_API_KEY, INVALID_API_KEY_FORMAT, INVALID_API_KEY — todos 401.

Validação

VALIDATION_ERROR — 400. Body tem campos inválidos, enum errado ou propriedade desconhecida.
MALFORMED_JSON — 400. Body não é JSON válido.
IMMUTABLE_FIELD — 400. Tentou mudar um campo que não pode ser editado depois da criação (ex.: toolType).

Estado de recurso

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.

Regras de negócio

NO_DRAFT_VERSION — 409. O agente não tem draft pra modificar; publique antes ou crie um novo draft.
SUB_AGENT_CYCLE — 422. Linkar criaria um ciclo (A → B → A).
OAUTH_NOT_SUPPORTED_VIA_API — 422. Registro OAuth requer o fluxo web do Studio.
CHANNEL_CONFIG_NOT_ALLOWED_VIA_API — 422. Config de WhatsApp requer Meta OAuth no Studio web.
HTTP_TOOL_LIMIT_REACHED — 422. Workspace atingiu o limite do plano.

Guia de retry

Status	Retry?
`400` / `404` / `409` / `422`	Não. Corrija a request.
`401`	Não. Corrija a key.
`408`	Às vezes. Aumente `timeoutSeconds` ou use streaming.
`429`	Sim, com backoff exponencial. Comece em 1s, max 30s.
`500` / `502`	Sim, com backoff exponencial. Se um `500` persistir, é bug — reporte.

Operações idempotentes (GET, DELETE) são sempre seguras para retry. Para POST / PATCH, faça retry só em falhas transientes (429, 502, erro de rede) para evitar criação dupla.

Começando

Convenções

Agents

Threads

Hub

Referência de status codes

Códigos de erro comuns

Autenticação

Validação

Estado de recurso

Regras de negócio

Guia de retry

​Referência de status codes

​Códigos de erro comuns

​Autenticação

​Validação

​Estado de recurso

​Regras de negócio

​Guia de retry

Referência de status codes

Códigos de erro comuns

Autenticação

Validação

Estado de recurso

Regras de negócio

Guia de retry