--- title: "Erros" description: "O formato das respostas de erro, todos os códigos e quais deles podem justificar uma nova tentativa." canonical: "https://atelier201.com/docs/pt/api/errors" updated: "2026-11-06" --- # Erros Todas as falhas têm o mesmo formato: ```json { "error": { "type": "not_found_error", "code": "resource_not_found", "message": "This site does not exist.", "docs_url": "https://atelier201.com/docs/api/errors#resource_not_found" }, "request_id": "req_01K9X7" } ``` **Use `code` para tomar decisões, nunca `message`.** Os códigos fazem parte do contrato; as mensagens são escritas para pessoas e podem ser aprimoradas com o tempo. Alguns erros incluem um objeto `details` com as informações necessárias para agir, como a revisão atual após um conflito de gravação. ## Quais erros permitem uma nova tentativa | Status | Tentar novamente? | | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 429 | Sim, após `Retry-After`. | | 5xx | Apenas para uma solicitação idempotente (GET, PUT, DELETE). Um POST que falha com 5xx talvez já tenha sido aplicado. Leia o recurso novamente antes de tentar. | | 4xx | Não. Há um problema na solicitação, que continuará com problema em uma nova tentativa. | ## Todos os códigos ### authentication\_required `authentication_error` · HTTP 401 Nenhuma credencial foi enviada. Adicione um cabeçalho `Authorization: Bearer`. ### invalid\_api\_key `authentication_error` · HTTP 401 A credencial não é reconhecida. Ela pode pertencer a um workspace que não existe mais. ### api\_key\_expired `authentication_error` · HTTP 401 A chave ultrapassou a data de validade. Crie uma nova. ### api\_key\_revoked `authentication_error` · HTTP 401 Alguém revogou a chave. A revogação é permanente. ### insufficient\_scope `permission_error` · HTTP 403 A credencial é válida, mas não recebeu o escopo necessário para este endpoint. A mensagem informa qual é. Emita uma nova credencial; não é possível ampliar o escopo de uma credencial existente. ### feature\_not\_available `permission_error` · HTTP 403 Este recurso não está incluído no plano. Ao tentar publicar um rascunho, a resposta informa isso: `details.blockers` contém `plan_required`, e `action_url` abre a página do plano do site. ### admin\_required `permission_error` · HTTP 403 A ação é restrita a pessoas administradoras do workspace: publicar, reverter, tirar um site do ar, excluir um site e alterar os domínios. ### invalid\_request `invalid_request_error` · HTTP 400 O corpo ou os parâmetros da consulta não passaram na validação. A mensagem indica o campo com problema. ### unknown\_field `invalid_request_error` · HTTP 400 Foi enviado um campo que este endpoint não aceita. As entradas são validadas com rigor de propósito: ignorar um campo silenciosamente poderia levar você a encontrar o problema muito mais tarde. ### invalid\_parameter `invalid_request_error` · HTTP 400 Um parâmetro tem formato incorreto, geralmente por ser um ID malformado. ### invalid\_cursor `invalid_request_error` · HTTP 400 O cursor de paginação não foi emitido por nós. Comece a listagem novamente. ### request\_too\_large `invalid_request_error` · HTTP 413 O corpo ultrapassou o limite máximo. ### resource\_not\_found `not_found_error` · HTTP 404 Esse objeto não existe neste workspace. O mesmo erro também é retornado para um recurso que pertence a outro workspace, de propósito: diferenciar os casos permitiria descobrir quais IDs existem. ### conflict `conflict_error` · HTTP 409 O recurso existe e a solicitação está bem formada, mas o estado atual dele impede a ação. Ao contrário de um erro 400, a ação pode ser bem-sucedida mais tarde. Causas comuns: - Conflito de gravação. Alguém alterou um arquivo desde a sua leitura. `details.reason` é `revision_conflict`, `details.current_revision` contém a revisão que deve ser lida, e `details.paths` lista cada arquivo com o hash esperado e o hash encontrado. - Tentativa de publicação usando uma revisão desatualizada, ou um build que não pode entrar no ar. Revise novamente e leia `details.blockers`. - Limite do plano, como o número máximo de rascunhos ou um domínio que excede o permitido pelo plano. A mensagem informa o limite, e `action_url` leva à página onde ele pode ser ampliado. ### result\_not\_ready `conflict_error` · HTTP 409 O processamento ainda não terminou, por exemplo, um site ainda está sendo criado. Aguarde alguns segundos em vez de tentar novamente imediatamente. ### idempotency\_key\_reused `conflict_error` · HTTP 409 A `Idempotency-Key` que você enviou a um endpoint compatível já foi usada para uma solicitação diferente neste workspace. Nada foi feito. Use uma chave nova para uma nova operação; repetir a mesma solicitação com a mesma chave retorna a resposta original. ### insufficient\_credits `invalid_request_error` · HTTP 402 Créditos insuficientes. **Pare e avise uma pessoa**; tentar novamente não vai ajudar. ### request\_too\_large\_for\_plan `invalid_request_error` · HTTP 422 O corpo está dentro do limite máximo, mas ultrapassa o permitido pelo plano. ### result\_expired `not_found_error` · HTTP 410 O resultado foi excluído pela política de retenção. Ele não será recuperado. ### rate\_limited `rate_limit_error` · HTTP 429 Excesso de solicitações. Aguarde o período indicado em `Retry-After` antes de tentar novamente. O mesmo período também está no corpo da resposta, como dados: `details.retry_after_seconds` e `details.retry_at` (uma data ISO), além de constar nos erros das ferramentas MCP e na saída JSON da CLI. ### internal\_error `api_error` · HTTP 500 Ocorreu uma falha do nosso lado. Informe o `request_id`. ### service\_unavailable `api_error` · HTTP 503 Uma dependência está fora do ar ou em manutenção. Tente novamente depois de aguardar um pouco.