Conceitos

Erros

Envelope de erro padrão da API v1 e a tabela completa de códigos mapeados para status HTTP.

Toda resposta da API v1 segue um envelope padrão. Em caso de erro, success é false e o objeto error traz um code estável e uma message legível:

JSON

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "..."
  }
}

(Em sucesso, o envelope é { "success": true, "data": { ... } }.)

Tabela de códigos

Código	HTTP	Quando
`UNAUTHORIZED`	401	Bearer token ausente ou inválido
`FORBIDDEN`	403	Token sem o escopo necessário
`NOT_FOUND`	404	Recurso inexistente ou fora do escopo do usuário
`VALIDATION_ERROR`	400	Body/parâmetros inválidos
`INSUFFICIENT_CREDITS`	402	Saldo de créditos insuficiente
`RATE_LIMITED`	429	Excedeu 60 req/min (com header `Retry-After`)
`MAX_CONCURRENT_TASKS`	429	Atingiu 20 tasks simultâneas
`SUBSCRIPTION_ALREADY_ACTIVE`	409	Já possui assinatura ativa (contate o suporte)
`INTERNAL_ERROR`	500	Erro interno (ex.: configuração ausente)
`GENERATION_FAILED`	502	Falha do provider de geração
`PROVIDER_UNAVAILABLE`	503	Provider indisponível

Os dois 429 são distintos: RATE_LIMITED traz Retry-After e é resolvido esperando; MAX_CONCURRENT_TASKS exige aguardar tasks em curso concluírem. Ver Rate limit & concorrência.