Guias › Integração
Erros e limites
Códigos de status, formato dos erros, créditos, idioma das mensagens e limites da API.
Formato dos erros#
Quando algo dá errado, a API responde com um status HTTP de erro e um JSON com a mensagem em error:
{ "error": "Agente não encontrado." }Alguns erros têm também um code estável. Use o code (e não o texto) para decidir o que fazer:
code | Status | Significado |
|---|---|---|
no_credits | 402 | Os créditos da organização acabaram. Um administrador precisa adicionar mais em Configurações › Uso e créditos. |
plan_required | 402 | A organização ainda não tem plano: só o primeiro diagnóstico é gratuito. O dono escolhe o plano em Configurações › Plano e cobrança. |
agent_budget | 402 | O agente atingiu o orçamento do mês. O responsável pode aumentar o limite nas configurações do agente; senão, ele volta quando o mês virar. |
no_provider | 400 ou 409 | Não há modelo de IA disponível para você. |
model_unavailable | 400 | O modelo pedido não está no catálogo ou não está liberado para você. |
provider_error | 502 | O provedor do modelo falhou. Tente de novo. |
Códigos de status#
| Status | Quando acontece |
|---|---|
200 / 201 | Deu certo. 201 quando algo foi criado. |
202 | Aceito e rodando em segundo plano (webhooks e triggers/{id}/run). |
400 | Corpo inválido: campo faltando, tamanho fora do limite, JSON malformado. A mensagem diz qual campo. |
401 | Sem chave, ou chave inválida ou revogada. |
402 | Sem créditos (no_credits), sem plano (plan_required) ou agente sem orçamento no mês (agent_budget). |
403 | Você vê o item mas não pode alterá-lo, ou a ação só funciona pelo navegador. |
404 | O item não existe ou você não tem acesso a ele. A API não diferencia os dois casos, para não revelar o que existe. |
409 | Conflito de estado: a conversa já está rodando, o gatilho está desligado ou o conector precisa ser reconectado. |
413 | Arquivo grande demais (o Brain aceita até 20 MB por arquivo). |
422 | O arquivo ou o texto chegou, mas não deu para usar: formato não suportado, PDF sem texto, frase que não vira um horário. |
5xx | Falha do servidor ou do provedor de IA. Tente de novo com espera crescente. |
Erros durante o streaming#
As rotas que respondem em streaming (conversa com agente e chat direto com modelo) já começaram a responder com 200 quando o problema aparece. Nesses casos o erro chega como um evento no meio do fluxo:
{"type":"error","message":"Os créditos da organização acabaram."}
{"type":"done","status":"failed"}Sempre trate o evento error e o done com status: "failed". Os detalhes estão em Conversas e Chat.
Créditos#
Quando a organização usa os modelos da plataforma, cada resposta consome créditos pelo custo do modelo. O consumo pela API e pela CLI sai do mesmo saldo do app.
- Antes de um uso grande, consulte o saldo com
GET /api/creditsoudoublex credits. - Sem saldo, o chat direto e a conversão de texto em horário respondem
402 no_credits. A conversa com agente responde com o eventoerrorno streaming. - Uma conversa cancelada ou que falhou no meio também cobra o que já foi processado.
Idioma das mensagens#
As mensagens de erro saem no idioma da pessoa dona da chave (um dos 14 do app, como Português, English, Español, Français ou 日本語), o mesmo escolhido no app. Para mudar pela API, use PATCH /api/me com {"language": "en"}. Se a pessoa ainda não escolheu um idioma, vale o cabeçalho Accept-Language da requisição e, sem ele, o idioma padrão da organização.
As mensagens de validação de formato (por exemplo, name: Too small) podem sair em inglês.
Limites#
| O quê | Limite |
|---|---|
| Mensagem para um agente | 100.000 caracteres |
| Tempo de uma resposta de agente | 800 segundos por mensagem |
| Conversas ao mesmo tempo | Uma resposta por conversa. Para rodar em paralelo, use conversas diferentes. |
| Arquivo no Brain | 20 MB por arquivo; texto acima de 2 milhões de caracteres é dividido em partes |
| Arquivo baixado de Criações | 2 MB |
| Resultado de ferramenta de conector | 20.000 caracteres |
| Gatilho agendado | No mínimo a cada 5 minutos |
| Corpo de webhook | 200.000 caracteres |
Não há limite de requisições por minuto, mas use o bom senso: prefira poucas chamadas maiores a muitas pequenas e não faça varreduras em laço.
Listas e paginação#
As listas (GET /api/agents, GET /api/tasks, GET /api/skills etc.) devolvem tudo o que você pode ver, sem paginação. Filtre no seu código ou use os filtros de cada rota.