Erros da API

Todos os erros da API Simple Agent seguem o mesmo formato JSON para facilitar o tratamento no seu código.

Formato padrão

{
  "error": {
    "code": "agent_not_found",
    "message": "Agent with ID 'ag_xyz' was not found or you don't have access.",
    "status": 404,
    "request_id": "req_01hwxyz..."
  }
}

Campo	Descrição
code	Identificador legível por máquina — use este para lógica condicional
message	Descrição humana do erro
status	HTTP status code
request_id	ID único do request — inclua ao contatar suporte

---

Códigos HTTP

Status	Quando ocorre
400	Request malformado — parâmetro ausente ou inválido
401	Token ausente ou inválido
403	Token válido mas sem permissão para este recurso
404	Recurso não encontrado
409	Conflito — ex: nome de agent duplicado
422	Entidade inválida — dados válidos mas semanticamente incorretos
429	Rate limit atingido
500	Erro interno — reportar com request_id
503	Serviço temporariamente indisponível

---

Códigos de erro comuns

Autenticação

Code	Causa	Solução
missing_auth_header	Header Authorization ausente	Adicione Authorization: Bearer af_live_xxx
invalid_token	Token malformado	Verifique se não há espaços ou caracteres extras
token_expired	Token expirou	Gere um novo token em Configurações → API
insufficient_scope	Token sem o escopo necessário	Crie um novo token com o escopo correto

Agents

Code	Causa	Solução
agent_not_found	ID inválido ou sem acesso	Confirme o ID no dashboard
agent_limit_reached	Limite de agents do plano atingido	Faça upgrade ou exclua um agent inativo
agent_name_taken	Nome já existe na sua conta	Use um nome diferente

Fontes

Code	Causa	Solução
source_not_found	Fonte não existe	Confirme o ID
url_not_accessible	URL bloqueou o crawler	Verifique robots.txt ou adicione como texto
pdf_too_large	PDF > 50MB	Comprima ou divida o arquivo
pdf_encrypted	PDF com senha não fornecida	Inclua o campo password no upload
indexing_in_progress	Reindexação em andamento	Aguarde e cheque status da fonte

Chat

Code	Causa	Solução
message_limit_reached	Cota de mensagens do mês esgotada	Aguarde renovação ou faça upgrade
context_too_long	Conversa muito longa para o modelo	Reinicie a conversa ou reduza o histórico
llm_timeout	LLM não respondeu em 30s	Tente novamente — ocorre raramente em picos

---

Tratamento de erros recomendado

async function apiRequest(url: string, options: RequestInit) {
  const res = await fetch(url, options);

  if (!res.ok) {
    const error = await res.json();

    switch (error.error.code) {
      case "rate_limit_exceeded":
        // Aguardar e tentar novamente
        await sleep(error.error.retry_after * 1000);
        return apiRequest(url, options);

      case "token_expired":
        // Redirecionar para renovação de token
        throw new AuthError("Token expirado. Gere um novo em Configurações → API.");

      case "message_limit_reached":
        // Notificar usuário
        throw new QuotaError("Limite de mensagens atingido neste mês.");

      default:
        // Log com request_id para debug
        console.error(`API Error [${error.error.request_id}]:`, error.error.message);
        throw new Error(error.error.message);
    }
  }

  return res.json();
}

---

Erros 500 — o que fazer

Erros 500 são raros e geralmente transitórios. Se persistirem por mais de 5 minutos:

1. Verifique o status da plataforma
2. Tente reproduzir com curl para isolar o problema
3. Abra um ticket em suporte@simple-agent.me incluindo o request_id

---

Status page

Acompanhe o status em tempo real em status.simple-agent.me. Você pode assinar notificações por email ou webhook para incidentes.

Rate Limits → · Autenticação → · Webhooks →