Codigos de erro

Referencia completa de erros HTTP, codigos especificos e como resolver cada um.

Copiar como .md

Toda resposta de erro segue o formato:

{
  "error": "Mensagem em portugues",
  "code": "MACHINE_READABLE_CODE",
  "details": { "field": "info opcional" }
}

Codigos HTTP

Status	Significado	Causas comuns
400	Bad Request	Body invalido, parametros faltando, JSON malformado
401	Unauthorized	API key ausente ou invalida
403	Forbidden	Sem permissao pra esse endpoint, conta nao verificada
404	Not Found	Recurso nao existe (sessionId, templateId, etc)
409	Conflict	Estado invalido (ex: sessao ja completada)
413	Payload Too Large	Arquivo > 500MB
422	Unprocessable Entity	Validacao de schema falhou
429	Too Many Requests	Rate limit excedido
500	Internal Server Error	Bug ou outage — abre ticket
503	Service Unavailable	Manutencao programada

Codigos especificos

Autenticacao

Code	Mensagem	Solucao
API_KEY_MISSING	API key nao fornecida	Adicione header X-API-Key
API_KEY_INVALID	API key invalida	Confira no painel se nao foi revogada
API_KEY_EXPIRED	API key expirou	Crie nova chave
PERMISSION_DENIED	Sem permissao pra este endpoint	Adicione permissao no painel
B2B_NOT_VERIFIED	Conta B2B nao verificada	Aguarde aprovacao (ate 48h)

Recursos

Code	Mensagem	Solucao
SESSION_NOT_FOUND	Sessao nao existe ou expirou	Crie nova sessao (sem sessionId)
SESSION_EXPIRED	Sessao expirou (2h inativa)	Crie nova com mesmo prompt
TEMPLATE_NOT_FOUND	Template nao existe	Confira o ID no painel
TEMPLATE_VARS_MISSING	Variaveis obrigatorias nao fornecidas	Passe templateVars com todas as vars
END_USER_NOT_FOUND	endUserId nao registrado	Crie via POST /end-users primeiro

Limites

Code	Mensagem	Solucao
PLAN_LIMIT_EXCEEDED	Limite do plano atingido	Faca upgrade ou aguarde reset mensal
NO_CREDITS	Sem creditos	Compre creditos avulsos ou faca upgrade
STORAGE_LIMIT_EXCEEDED	Limite de storage atingido	Delete arquivos antigos ou faca upgrade
FILE_TOO_LARGE	Arquivo excede 500MB	Reduza ou divida o arquivo
RATE_LIMIT_EXCEEDED	Muitos requests	Aguarde Retry-After segundos

Processamento

Code	Mensagem	Solucao
PROCESSING_FAILED	IA falhou ao processar	Tente de novo ou reformule prompt
UNSUPPORTED_FILE_TYPE	Tipo de arquivo nao suportado	Confira lista de formatos aceitos
PROMPT_TOO_LONG	Prompt excede limite de tokens	Reduza tamanho ou use template

Rate Limiting

Headers de resposta

Toda resposta tem headers indicando seu limite:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1714320000

Quando excede (429)

{
  "error": "Rate limit excedido. Tente novamente em 45 segundos.",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 1000,
    "window": "1m",
    "retryAfter": 45
  }
}

Header Retry-After indica quantos segundos aguardar.

Limites por plano

Plano	Requests/min	Tokens/dia	Storage
Trial	60	50k	500MB
Starter	300	500k	5GB
Pro	1000	5M	50GB
Business	5000	50M	500GB
Enterprise	Ilimitado	Negociavel	Negociavel

Boas praticas

Retry com backoff exponencial

Pra erros 429, 500, 502, 503, 504 — implemente retry:

async function callWithRetry(url: string, opts: RequestInit, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const res = await fetch(url, opts);

    if (res.ok) return res;
    if (![429, 500, 502, 503, 504].includes(res.status)) return res;

    const retryAfter = parseInt(res.headers.get('Retry-After') || '0', 10);
    const wait = retryAfter > 0 ? retryAfter * 1000 : Math.min(2 ** attempt * 1000, 30000);
    await new Promise(r => setTimeout(r, wait));
  }
  throw new Error('Max retries excedidos');
}

Logue code em vez da mensagem

Mensagens em portugues podem mudar; code e estavel:

if (response.code === 'NO_CREDITS') {
  // Mostra modal de upgrade
}

Nao retry de 4xx

Erros 400, 401, 403, 404, 422 sao do seu lado — retry nao resolve. So 429/5xx valem retry.

Reportar bugs

Se encontrar um 500 que parece bug, abra ticket em:

• docs/suporte
• Ou email: suporte@buildship.com.br

Anexe:

• Endpoint chamado
• Request body (sem dados sensiveis)
• Status + response body
• Timestamp UTC