Erros

Todo erro vem como application/problem+json (RFC 9457), com um code estável para o seu código decidir o que fazer.

{
  "type": "https://aideed.com.br/desenvolvedores/erros#quota_exhausted",
  "title": "Laura já fez as 3000 tarefas do mês incluídas no salário. Libere hora extra na integração para continuar.",
  "status": 429,
  "code": "quota_exhausted",
  "request_id": "req_4f1c2a9b0d3e7f61"
}

title é uma mensagem em português, pronta para mostrar a quem usa o seu sistema.
detail aparece em erros de validação, apontando o campo.
request_id também vem no cabeçalho X-Request-Id de toda resposta. Informe-o ao suporte.

Códigos

Código	HTTP	O que fazer
`unauthorized`	401	Chave ausente, inválida, revogada ou de integração suspensa. Confira o cabeçalho `Authorization: Bearer …`.
`insufficient_scope`	403	A integração não tem a permissão que a chamada pede (ex.: `webhooks:manage`). A empresa ajusta as permissões no painel.
`not_found`	404	O recurso não existe para esta integração. Ids de outra empresa também respondem 404.
`invalid_request`	422	Corpo ou parâmetro inválido; `detail` aponta o campo.
`agent_unavailable`	409	O agente não está disponível agora (pausado ou desligado).
`task_not_finished`	409	O resultado ainda não existe. Consulte o status e tente depois.
`task_finished`	409	A tarefa já terminou e não pode mais ser cancelada.
`rate_limited`	429	Limite de requisições ou de tarefas por segundo atingido. Espere o `Retry-After`.
`quota_exhausted`	429	O agente usou as tarefas do mês e a integração não tem hora extra liberada.
`overtime_cap_reached`	429	A hora extra do mês chegou ao teto definido pela empresa para esta integração.
`revoked`	400	A integração foi revogada e não aceita mudanças.
`wrong_channel`	403	A integração está liberada só para MCP (ou só para a API). A empresa muda o acesso no painel.

Falhas do próprio agente não viram erro HTTP: a tarefa termina com status failed e um error com código e mensagem simples (ex.: agent_failed, timeout).

Mais do portal

Comece aqui: Visão geral · Primeiros passos

Guias: Autenticação · Conceitos · Tarefas e aprovações · Webhooks · Erros · Limites e cota · Ambiente de testes · MCP do Workforce

Referência: Referência da API · Exemplos de código · Versões e mudanças

Dados públicos: API pública do catálogo · MCP do catálogo público