Erros e limites de taxa

Formato do erro

Toda resposta fora da faixa 2xx é um JSON no formato:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the `generation:run` scope.",
    "required_scope": "generation:run",
    "granted_scopes": ["books:read"]
  }
}

Códigos comuns

HTTP	`error.code`	Significado
400	`invalid_request`	O corpo ou a query não passou na validação do esquema.
400	`invalid_state`	O livro/capítulo existe, mas não está em um estado que permita a ação (por exemplo, publicar um livro com capítulos vazios).
400	`unreadable`	O arquivo não pôde ser lido ou não tem texto utilizável (por exemplo, um PDF digitalizado).
401	`unauthenticated`	Cabeçalho Authorization ausente ou malformado.
401	`invalid_token`	Token desconhecido, expirado ou revogado.
403	`insufficient_scope`	O token é válido, mas não tem o escopo que o endpoint exige — gere uma nova chave com o escopo indicado.
404	`not_found`	O livro ou capítulo não existe (ou não pertence a você).
413	`payload_too_large`	O arquivo ou o corpo da requisição é grande demais. Para manuscritos, o limite também vale para o texto extraído, que pode ultrapassá-lo em arquivos EPUB ou Word compactados.
502	`generation_failed`, `narration_failed`	O provedor externo (Anthropic, ElevenLabs) falhou. Pode tentar de novo com segurança.
503	`feature_disabled`	A instância da Anthra não tem configurada a chave externa necessária (por exemplo, ELEVENLABS_API_KEY para narração).

Limites de taxa

A Anthra aplica cotas por conta às operações caras (geração de capítulos, narração). Quando você atinge um limite, recebe um HTTP 429 com retry-after indicando quantos segundos esperar. O corpo do 429 usa o mesmo formato de erro.

As tarefas de geração também são limitadas por maxDuration = 300s nas Vercel Functions — escritas de capítulo que realmente precisem de mais tempo devem ser reenviadas (o conteúdo parcial já fica salvo antes do tempo limite).

Idempotência

Hoje, os endpoints que alteram dados não são idempotentes. Use uma chave única por requisição (por exemplo, POST /v1/books sempre cria um novo livro). Se você precisa de semântica de no máximo uma vez, elimine duplicatas no cliente antes de tentar de novo.