Erros
O formato das respostas de erro, todos os códigos e quais deles podem justificar uma nova tentativa.
Todas as falhas têm o mesmo formato:
{
"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_revisioncontém a revisão que deve ser lida, edetails.pathslista 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_urlleva à 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.