DoubleX AgentesDocs

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:

JSON
{ "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:

codeStatusSignificado
no_credits402Os créditos da organização acabaram. Um administrador precisa adicionar mais em Configurações › Uso e créditos.
plan_required402A 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_budget402O 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_provider400 ou 409Não há modelo de IA disponível para você.
model_unavailable400O modelo pedido não está no catálogo ou não está liberado para você.
provider_error502O provedor do modelo falhou. Tente de novo.

Códigos de status#

StatusQuando acontece
200 / 201Deu certo. 201 quando algo foi criado.
202Aceito e rodando em segundo plano (webhooks e triggers/{id}/run).
400Corpo inválido: campo faltando, tamanho fora do limite, JSON malformado. A mensagem diz qual campo.
401Sem chave, ou chave inválida ou revogada.
402Sem créditos (no_credits), sem plano (plan_required) ou agente sem orçamento no mês (agent_budget).
403Você vê o item mas não pode alterá-lo, ou a ação só funciona pelo navegador.
404O 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.
409Conflito de estado: a conversa já está rodando, o gatilho está desligado ou o conector precisa ser reconectado.
413Arquivo grande demais (o Brain aceita até 20 MB por arquivo).
422O 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.
5xxFalha 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:

NDJSON
{"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/credits ou doublex 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 evento error no 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 agente100.000 caracteres
Tempo de uma resposta de agente800 segundos por mensagem
Conversas ao mesmo tempoUma resposta por conversa. Para rodar em paralelo, use conversas diferentes.
Arquivo no Brain20 MB por arquivo; texto acima de 2 milhões de caracteres é dividido em partes
Arquivo baixado de Criações2 MB
Resultado de ferramenta de conector20.000 caracteres
Gatilho agendadoNo mínimo a cada 5 minutos
Corpo de webhook200.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.