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: ```json { "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 | ### 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) ```json { "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: ```ts 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: ```ts 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](/docs/suporte) - Ou email: suporte@buildship.com.br Anexe: - Endpoint chamado - Request body (sem dados sensiveis) - Status + response body - Timestamp UTC