Revisado em 2026-11-10 · Versão da API 2026-11-09 · Ler Markdown
Erros, repetições e recuperação
Os erros da API usam { "error": { "code": "…", "message": "…", "requestId": "…" } }
com erros de campo opcionais, erros de destino, dicas de repetição e transferências de ação.
Preserve o requestId para o suporte. Não registre em log credenciais, URLs de upload assinadas nem
conteúdo sensível de requisições ao coletar diagnósticos.
| Resposta | Recuperação |
|---|---|
401 unauthenticated | Verifique a chave de produto ausente, malformada ou revogada |
403 forbidden_scope / account_not_allowed | Revise os escopos da chave e o acesso ao destino |
402 account_limit, seat_limit, storage_limit | Revise a titularidade do espaço de trabalho e o uso de recursos |
402 subscription_inactive / trial_expired | Resolva o estado de cobrança; preserve rascunhos e trabalho em fila |
409 revision_conflict | Leia a versão atual, revise as alterações e reaplique intencionalmente |
409 idempotency_conflict | A chave foi reutilizada com um corpo diferente; reconcilie a operação original |
409 consent_required | Peça a uma pessoa autorizada que conclua a transferência de revisão fornecida |
409 too_late_to_cancel | Inspecione o status real da entrega; não afirme que o cancelamento foi bem-sucedido |
media_expired / media_deleting | Reenvie os originais e atualize o rascunho |
422 validation_failed | Corrija os campos estruturados ou os problemas por destino |
429 rate_limited | Respeite o Retry-After; reduza a concorrência e use backoff |
submission_unknown | Reconcilie o resultado externo existente antes de tentar outro envio |
Repetições seguras de mutações
Gere uma chave de idempotência antes da primeira mutação e armazene a requisição exata dela.
Se a resposta se perder, a operação pode já ter sido concluída com sucesso. Repita a
mesma requisição com a mesma chave; nunca gere uma chave nova meramente porque a
rede atingiu o tempo limite. As ferramentas de mutação do MCP ecoam as chaves delas, inclusive em
falhas transport_outcome_unknown. O adaptador não repete mutações automaticamente.
Os limites técnicos de velocidade do espaço de trabalho não são créditos de publicação. Use /usage para as
informações atuais de plano e de taxa. Recue apenas para erros transitórios, quando
apropriado; repetir erros de autorização, validação ou consentimento humano sem
mudar a causa deles não ajuda.
Sucesso parcial e observação
Um lote de publicação/agendamento aceito é um conjunto de entregas independentes. Guarde os recibos bem-sucedidos e os links nativos. Recupere um destino com falha por meio do endpoint de repetição dele, em vez de criar o lote inteiro novamente. Prefira webhooks assinados; se usar sondagem, faça um número limitado de tentativas com atrasos crescentes e encaminhe o trabalho não resolvido a uma pessoa.