Códigos de erro Envelope de resposta, formato de erro e referência de todos os códigos retornados pelas ferramentas.
{ "success" : true , "trace_id" : "550e8400-e29b-41d4-a716-446655440000" , "data" : {}, "meta" : {} } Campo Descrição successtrue em respostas OKtrace_idID de correlação (também no header X-Trace-Id) dataRecurso ou resultado metaOpcional — custo (meta.cost), paginação etc.
Com X-Include-Cost: true ou em dry-run, meta traz o custo da operação — veja os formatos em Dry-run . Listagens trazem a paginação dentro de data (total e, no PDF, page e page_size), não em meta.
{ "success" : false , "trace_id" : "550e8400-e29b-41d4-a716-446655440000" , "error" : { "code" : "billing.insufficient_credits" , "message" : "Créditos insuficientes para esta operação." , "details" : { "required" : 100 , "available" : 50 } } } Campo Descrição error.codeIdentificador estável — trate erros por ele, nunca pela message error.messageTexto legível; pode mudar entre versões error.detailsContexto estruturado opcional; em validation.failed, details.fields traz os erros por campo trace_idInforme em tickets de suporte
Código HTTP Quando auth.missing_token401 Header de autenticação não enviado. auth.invalid_token401 Token malformado. auth.unauthorized401 Token inválido, expirado ou revogado. auth.email_not_verified403 E-mail da conta ainda não verificado. scope.missing403 Token sem o escopo exigido pela rota (details.required, details.provided). tool.disabled403 A ferramenta ainda não está liberada para a conta: está desligada ou em testes com contas selecionadas. Ferramentas com código próprio (como rag.disabled) respondem com ele. forbidden403 A chave não pode fazer esta ação (ex.: chave restrita a bases de conhecimento específicas tentando criar uma base).
Código HTTP Quando billing.insufficient_credits402 Saldo insuficiente para a operação. billing.user_bankrupt402 Conta suspensa por saldo negativo. billing.spend_limit_reached402 A cobrança passaria do limite diário de gasto da chave (details.limit, details.spent_today, details.required). billing.call_limit_exceeded402 Uma única cobrança passaria do teto por chamada da conexão MCP (max_call_credits).
Código HTTP Quando validation.failed400 Payload inválido; veja details.fields. validation.invalid_id400 UUID ou ID malformado. idempotency.conflict409 Chave de idempotência reutilizada com payload diferente. not_found404 Recurso inexistente, de outra conta ou fora das restrições da chave. conflict409 O recurso está num estado que não permite a operação (ex.: documento sendo excluído). rate_limit.exceeded429 Limite de requisições excedido; aguarde X-RateLimit-Reset.
Código HTTP Quando mcp.disabled404 Servidor MCP desligado. mcp.agents_disabled403 Acesso de agentes de IA desligado na conta (botão de pânico no dashboard). mcp.tool_disabled403 Ferramenta desligada temporariamente para agentes. mcp.timeout504 A ferramenta passou do tempo limite; tente de novo. mcp.result_too_large400 Resultado acima de 32 KB; peça menos itens ou response_format=concise. mcp.tools_search_rate_limited429 Mais de 60 chamadas de tools_search por minuto.
Código HTTP Quando internal.unexpected500 Erro interno inesperado. Informe o trace_id ao suporte. gateway.timeout504 Um serviço interno demorou demais para responder; tente de novo.
Código HTTP Quando video.spec_invalid400 VideoSpec fora do schema ou dos limites (o erro traz o caminho do campo). video.asset_invalid400 Um asset do vídeo não pôde ser usado. video.retention_invalid400 Retenção do render inválida. video.price_above_max409 O preço do render passa de max_credits; nada é cobrado. video.too_many_in_flight429 Renders demais em andamento na conta; espere algum terminar. video.not_ready409 O render ainda não terminou. video.not_cancelable409 O render já terminou e não pode ser cancelado. video.not_found404 Render inexistente ou de outra conta. video.unavailable503 Renderização de vídeo indisponível no momento. video.enqueue_failed500 Falha ao enfileirar o render. video.internal500 Erro interno ao processar o vídeo. video.preview_time_invalid400 O instante t do quadro está fora da duração do vídeo. video.preview_busy503 Há prévias demais em andamento; tente de novo em instantes. video.preview_failed422 Não foi possível renderizar o quadro de prévia.
Código HTTP Quando dynamic_qr.name_required400 Campo name obrigatório. dynamic_qr.invalid_url400 URL de destino inválida. dynamic_qr.invalid_slug400 Slug fora do padrão [a-zA-Z0-9-]{3,50}. dynamic_qr.malicious_url403 URL bloqueada pela verificação de segurança. dynamic_qr.not_found404 QR inexistente ou de outra conta. dynamic_qr.slug_taken409 Slug já em uso. dynamic_qr.invalid_rules400 Regra de redirect inválida: sem condição, id repetido, valor de condição desconhecido ou mais de 20 regras. dynamic_qr.invalid_variants400 Teste A/B inválido: de 2 a 10 variantes, id único, weight de 1 a 1000 e target_url absoluta. dynamic_qr.invalid_pixels400 ID de pixel fora do formato (GA4 G-XXXX, Meta só dígitos, GTM GTM-XXXX). dynamic_qr.invalid_fallback_urls400 expired_url e limit_reached_url precisam ser URLs absolutas.dynamic_qr.invalid_content400 Conteúdo hospedado inválido para o type informado. dynamic_qr.folder_not_found404 Pasta inexistente ou de outra conta. dynamic_qr.folder_taken409 Já existe uma pasta com esse nome. dynamic_qr.folder_invalid400 O nome da pasta tem de 1 a 80 caracteres. dynamic_qr.tags_invalid400 Tags inválidas: até 20 por QR, até 40 caracteres cada e sem vírgula ou ponto e vírgula. dynamic_qr.bulk_invalid400 Edição em massa inválida: action desconhecida, de 1 a 500 ids ou campo exigido pela ação ausente. dynamic_qr.batch_not_found404 Lote inexistente ou de outra conta. dynamic_qr.batch_invalid400 Lote sem linhas ou CSV malformado (sem cabeçalho, coluna desconhecida ou sem target_url). dynamic_qr.batch_too_large413 Mais de 1.000 linhas no lote. dynamic_qr.scan_range_invalid400 from/to/before fora do formato YYYY-MM-DD.qr_domain.invalid_hostname400 O hostname precisa ser um subdomínio público, como qr.suaempresa.com (sem porta, caminho, IP ou curinga). qr_domain.not_found404 Domínio inexistente ou de outra conta. qr_domain.taken409 Esse hostname já está cadastrado. qr_domain.in_use409 Há QRs usando o domínio; exclua-os ou mova-os antes de remover. qr_domain.not_usable409 O domínio falhou ou está suspenso e não aceita novos QRs. qr_domain.plan_limit403 O plano não permite mais domínios próprios. qr_domain.unavailable503 Domínios próprios indisponíveis no momento. qr_domain.provider_failed502 O provedor de certificados recusou ou não respondeu; tente de novo. dynamic_qr.generation_failed502 Falha ao gerar o QR. dynamic_qr.image_generation_failed502 Falha ao renderizar a imagem do QR.
Código HTTP Quando pdf.invalid_request400 Corpo da requisição inválido. pdf.html_required400 html e url ausentes: envie um dos dois.pdf.html_too_large400 HTML acima de 10 MB. pdf.css_too_large400 CSS acima de 1 MB. pdf.invalid_page_size400 Tamanho de página inválido. pdf.invalid_format400 Formato diferente de pdf, png ou jpg. pdf.invalid_url400 url (ou google_fonts_url) inválida: precisa ser um endereço público http/https de até 2048 caracteres.pdf.invalid_option400 Opção inválida ou combinação não permitida (html com url, post_process fora do formato pdf, pdfa com protection, template_id com html…). pdf.template_not_found404 Template (ou versão) não encontrado na conta. pdf.font_not_found404 Fonte não encontrada na conta. pdf.font_invalid400 Fonte inválida: arquivo ausente, acima de 5 MiB, que não seja woff2/ttf, ou family, weight ou style fora do permitido. pdf.font_exists409 Já existe uma fonte com a mesma família, peso e estilo. pdf.font_limit400 Limite de 50 fontes por conta atingido. pdf.retention_invalid400 retention_days inválido.pdf.batch_empty400 Batch sem itens. pdf.batch_too_large400 Mais de 500 itens no batch. pdf.template_required400 Template HTML obrigatório no batch. pdf.not_completed400 Download solicitado antes de a conversão terminar. pdf.no_file400 Arquivo não disponível (expirado ou não gerado). pdf.download_failed400 Falha ao ler ou descomprimir o arquivo. pdf.decrypt_failed400 Falha ao preparar o arquivo para download. pdf.render_failed502 Falha no render. pdf.storage_failed502 Falha ao armazenar o arquivo. pdf.enqueue_failed502 Falha ao enfileirar o job. pdf.render_timeout504 Tempo esgotado no render. pdf.internal500 Erro interno ao processar a conversão. pdf.template_failedassíncrono Falha ao aplicar os dados do item no template (batch).
Código HTTP Quando tools.safety.invalid_url400 Parâmetro url ausente ou inválido. tools.safety.domain_required400 Parâmetro domain ausente. tools.safety.favicon_not_found404 Favicon não encontrado para o domínio.
Código HTTP Quando rag.disabled403 Base de conhecimento ainda não liberada para a conta. rag.document_too_large413 Conteúdo acima de 5 MB. rag.chunk_quota_exceeded403 A conta passaria de 200.000 trechos indexados. rag.collection_limit_reached403 Limite de 50 bases por conta. rag.too_many_pending_documents429 Já há 20 documentos em processamento; aguarde alguns terminarem. rag.capacity_exhausted429 Serviço de busca sem capacidade no momento; tente de novo em alguns segundos. rag.embedding_failed502 Falha no serviço de embeddings. rag.feedback_rate_limited429 Mais de 30 votos de feedback por minuto. rag.document_not_failed409 Só documentos com status failed podem ser reprocessados. rag.collection_create_restricted403 A conexão MCP está limitada a bases específicas e não pode criar bases novas. rag.model_switch_in_progress409 A base está trocando de modelo de busca; envie documentos quando a troca terminar ou cancele-a. rag.service_unavailable503 Serviço de rerank (inclusive o Laya), conversão de arquivo, analytics ou chaves públicas indisponível no momento. rag.decrypt_failed500 Falha ao ler o conteúdo guardado. Informe o trace_id ao suporte. embedding_failedassíncrono A indexação do documento falhou; use o reprocessamento. insufficient_creditsassíncrono Saldo ou limite diário insuficiente para cobrar a ingestão ao terminar. empty_documentassíncrono O documento não tem texto indexável. chunk_quota_exceededassíncrono A ingestão passaria do limite de trechos da conta. persist_failedassíncrono Falha ao gravar o resultado; a cobrança é estornada. enqueue_failedassíncrono Falha ao enfileirar a ingestão.
Código HTTP Quando webhook.relay_disabled403 Webhook Relay ainda não liberado para a conta. webhook.limit_reached403 Limite da conta atingido: projetos, endpoints, tipos de evento, fontes ou rotas por fonte. Os limites valem para a conta inteira, somando todos os projetos; ao duplicar um projeto, nada é criado. webhook.payload_invalid422 payload não é JSON válido ou não segue o JSON Schema do tipo de evento. Nada é cobrado.webhook.invalid_url400 URL de destino inválida ou restrita: só URLs públicas http/https (também vale para a webhook_url do PDF). webhook.invalid_event400 Evento desconhecido na API legada de webhooks da conta (/v1/account/webhooks, obsoleta). No Webhook Relay qualquer nome de evento válido é aceito.
Código HTTP Quando realtime.disabled403 Realtime ainda não liberado para a conta (na conexão WebSocket, close 4003). realtime.token_invalid401 Token de conexão inválido ou expirado; na conexão WebSocket, close 4001. Emita um token novo. realtime.capability_denied403 O token não permite a operação (subscribe, publish ou presence) no canal; no WebSocket, frame error com channel e a conexão continua aberta. realtime.channel_invalid400 Nome de canal ou padrão de canal inválido: vazio, com mais de 128 caracteres ou com caracteres fora de A-Z a-z 0-9 : _ - .. realtime.message_too_large413 Mensagem (data) acima de 64 KB. realtime.rate_limited429 A conta passou do limite de publicações por segundo; a mensagem é descartada e, no WebSocket, a conexão continua aberta. realtime.connection_limit429 A conta atingiu o limite de conexões simultâneas (WebSocket: close 4029). Reconecte com backoff. realtime.presence_limit429 O canal já tem o máximo de membros na presença (200). realtime.insufficient_credits402 Saldo insuficiente para publicar uma mensagem além da franquia mensal. realtime.session_required403 A rota só aceita a sessão do dashboard (POST /inspector-token), não uma chave de API.
Código HTTP Quando tools.ci.log_required400 Campo log ausente ou vazio. tools.ci.log_too_large413 Log acima do tamanho máximo aceito.
Código HTTP Quando tools.web.invalid_url400 Campo url ausente ou inválido (só http e https). tools.web.blocked_url400 URL recusada: aponta para um endereço interno ou privado. tools.web.fetch_failed502 Não foi possível baixar a página. tools.web.not_html422 O endereço não devolveu uma página HTML. tools.web.too_large413 Página acima do tamanho máximo aceito. tools.web.no_content422 Nenhum conteúdo de texto encontrado na página (por exemplo, página que depende de JavaScript).
Código HTTP Quando notify.invalid_channel400 Canal inválido: tipo desconhecido ou campos que não combinam com o tipo (URL do webhook, servidor e tópico do ntfy). notify.channel_not_found404 Canal inexistente ou de outra conta. notify.channel_name_taken409 Já existe um canal com esse nome na conta. notify.channel_disabled409 O canal escolhido está desativado. notify.rate_limited429 Limite de notificações por período excedido; tente de novo mais tarde. notify.delivery_failed502 Não foi possível entregar a notificação no canal (nada é cobrado). notify.unavailable503 O envio de notificações está indisponível no momento; tente de novo em alguns segundos.
Código HTTP Quando audio.disabled403 Áudio ainda não liberado para a conta. audio.input_invalid400 Corpo inválido, ou áudio informado de forma errada (mande exatamente um entre audio_url, audio_base64 e file_id). audio.input_blocked400 A URL do áudio aponta para um endereço não permitido (rede interna ou privada), ou a descrição de audio_generate pede imitação de artistas, vozes ou obras. Nada é cobrado. audio.too_long400 Áudio acima de 60 minutos, ou texto acima de 5.000 caracteres: recusado antes de cobrar. audio.input_too_large413 Arquivo de áudio acima de 25 MB (ou 10 MB em audio_base64). audio.format_unsupported415 Formato de áudio não suportado; use mp3, wav, ogg, m4a, flac ou webm. audio.input_fetch_failed502 Não foi possível baixar o áudio da audio_url. audio.provider_failed502 O motor de áudio falhou; a cobrança é devolvida. audio.input_timeout504 O download do áudio passou de 30 segundos. audio.price_above_max409 O preço passa de max_credits; nada é cobrado. audio.pricing_unavailable503 Preço do serviço de áudio indisponível no momento; tente de novo. audio.not_found404 Job de áudio inexistente, de outra conta ou já expirado. audio.voice_unknown400 Voz inexistente ou apagada: use um id de GET /audio/voices ou uma voz clonada da conta que já esteja pronta. audio.consent_required400 voice_create sem o consentimento aceito, ou com versão dos termos desatualizada (leia os termos com dry_run).audio.voice_sample_rejected422 Amostra recusada: sem a frase de consentimento lida em voz alta, com mais de uma voz ou fora de 10 a 60 segundos. O valor é devolvido. audio.voice_limit409 A conta já tem o máximo de 3 vozes clonadas; apague uma com voice_delete. audio.voice_rate_limited429 Limite de criações de voz por dia (5) ou de usos por hora (60) atingido.
Jobs assíncronos (PDF) também expõem error_code no próprio recurso quando status é failed; códigos marcados como assíncrono aparecem apenas ali.
Trate 402 com um fluxo de recarga no seu sistema.
Em 429, respeite X-RateLimit-Reset antes de tentar de novo.
Use X-Dry-Run para capturar validation.failed sem custo.
Repita apenas erros 5xx e de rede, sempre com a mesma X-Idempotency-Key.
Registre o trace_id de toda resposta com erro.
Atualizado em 12 de outubro de 2026
