Erros da API - Base de conhecimento

Erros

A API usa os códigos de status HTTP convencionais para indicar o resultado e um corpo JSON estruturado para descrever o motivo. Toda resposta de erro tem o mesmo formato: o código, uma mensagem curta e, quando houver, detail com contexto adicional.

{  "error": {    "code": 400301,    "message": "invalid uuid format",    "detail": "see https://en.wikipedia.org/wiki/Universally_unique_identifier"  }}

{
  "error": {
    "code": 400301,
    "message": "invalid uuid format",
    "detail": "see https://en.wikipedia.org/wiki/Universally_unique_identifier"
  }
}

Campos:

Campo	Tipo	Descrição
`error.code`	`number`	Código detalhado no nível da aplicação. Combina o status HTTP com a categoria do motivo — a lista completa está abaixo.
`error.message`	`string`	Explicação curta em linguagem natural, adequada para logs.
`error.detail`	`string`	Opcional. Contexto adicional: a lista de campos que falharam na validação, um link para documentação externa ou o valor que foi rejeitado.

Resumo dos códigos de status HTTP

Código	Nome	Descrição
200	OK	A requisição foi concluída. O corpo da resposta traz o objeto solicitado.
201	Created	O recurso foi criado. O corpo da resposta traz o novo objeto.
204	No Content	A requisição foi concluída, mas o endpoint não tem corpo para devolver (em geral, depois de um `DELETE`).
400	Bad Request	A requisição está malformada: faltam campos obrigatórios, os tipos estão errados ou os valores dos parâmetros são inválidos.
401	Unauthorized	A autenticação está ausente, inválida ou expirada. Verifique o cabeçalho `Authorization`.
402	Payment Required	O plano ou o saldo do workspace não cobre esta operação.
403	Forbidden	O token está autenticado, mas não tem permissão para este recurso ou ação.
404	Not Found	O recurso não existe ou existe, mas não é visível para este token.
429	Too Many Requests	O limite de requisições foi excedido. Respeite o cabeçalho `Retry-After` da resposta antes de tentar de novo.
5xx	Server Error	Erro inesperado no servidor. É seguro repetir a requisição com backoff exponencial; se persistir, fale com o suporte.

Códigos numéricos devolvidos em error.code. Os três primeiros dígitos de cada código sempre coincidem com o status HTTP da resposta.

Códigos de autenticação e acesso (1xxxxx)

Código	Nome	Descrição
1	`IO_ERROR`	Não foi possível ler o corpo da requisição — normalmente um payload vazio ou malformado, ou uma conexão interrompida durante o envio.
100101	`AUTH_AUTHORIZATION_HEADER_NOT_FOUND`	O cabeçalho `Authorization` não veio na requisição.
100102	`UNAUTHORIZED`	O token está ausente, inválido ou expirado.
100103	`ACCESS_DENIED`	O token é válido, mas não dá acesso a este recurso ou escopo.
100104	`INVALID_USERNAME_OR_PASSWORD`	As credenciais enviadas ao endpoint de login não correspondem a nenhuma conta.
100105	`INVALID_CONFIRMATION_TOKEN`	O token de confirmação de e-mail é desconhecido ou expirou. Solicite um novo.
100106	`LIMIT_REACHED`	Uma cota ou um limite de requisições do workspace foi atingido.
100107	`USER_IS_NOT_OWNER`	A ação exige privilégios de dono do workspace, e o usuário atual não é o dono.

Códigos de requisição inválida e validação (4xxxxx)

Código	Nome	Descrição
400101	`JSON_SYNTAX_ERROR`	O corpo da requisição não é um JSON válido.
400102	`JSON_UNMARSHAL_TYPE_ERROR`	Um campo do corpo tem um tipo que a API não esperava (por exemplo, uma string onde é preciso um número).
400201	`HAS_ALREADY_BEEN_TAKEN`	Uma restrição de unicidade foi violada: já existe um valor com a chave informada.
400202	`EMAIL_IS_ALREADY_TAKEN`	Já existe uma conta com este endereço de e-mail.
400203	`NAME_IS_ALREADY_TAKEN`	Já existe uma entidade com este nome no escopo atual (workspace, projeto, pasta).
400204	`INVITATION_IS_ALREADY_EXIST`	Um convite já foi enviado para este destinatário.
400205	`INVITATION_IS_ALREADY_APPROVED`	O convite já foi aceito e não pode ser aceito de novo.
400206	`BILLING_ACCOUNT_IS_ALREADY_EXIST`	Já existe uma conta de cobrança vinculada a este workspace.
400207	`NOT_ENOUGH_MONEY`	O saldo do workspace não é suficiente para esta operação.
400208	`NO_BILLING_ACCOUNT`	O workspace ainda não tem conta de cobrança. Crie uma antes de usar recursos pagos.
400209	`NO_PAYMENT_METHOD`	Nenhuma forma de pagamento está configurada na conta de cobrança.
400210	`NOT_ENOUGH_REQUIRED_PRODUCTS`	Faltam no plano atual um ou mais produtos dos quais esta operação depende.
400211	`NOT_ALLOWED_ADDITIONAL_FOR_TRIAL`	Não é possível comprar adicionais enquanto o workspace estiver no plano de teste.
400212	`SUBSCRIPTION_NOT_PAID`	O workspace tem faturas em aberto. Quite-as antes de continuar.
400213	`EMAIL_NOT_CONFIRMED`	O endereço de e-mail do usuário ainda não foi confirmado.
400214	`EMAIL_NOT_FOUND`	Nenhuma conta está associada ao e-mail informado.
400215	`RESET_TOKEN_NOT_FOUND_OR_EXPIRED`	O token de redefinição de senha é desconhecido ou expirou. Comece o processo novamente.
400216	`NOT_ALLOWED_ORDER_FIELD`	O parâmetro `order` aponta para um campo pelo qual este endpoint não sabe ordenar.
400301	—	Um dos parâmetros UUID na URL, na query ou no corpo tem formato inválido.
400400	`UNEXPECTED_VALUE`	O valor de um parâmetro está fora do conjunto de valores permitidos (em geral, um enum).

Outros códigos de erro (402 / 404 / 500)

Código	Nome	Descrição
402402	`VALIDATION_ERROR`	Um ou mais campos falharam na validação. O campo `detail` costuma listar os campos com erro e os motivos.
404404	`NO_SUCH_ENTITY`	O objeto referenciado não existe, foi excluído ou não é visível para este token.
500500	`INTERNAL_SERVER_ERROR`	Ocorreu um erro inesperado no servidor. É seguro repetir a requisição com backoff exponencial.

Tratamento de erros

Novas tentativas. É seguro repetir requisições que devolveram 5xx ou estouraram o tempo de espera da rede. Use backoff exponencial e limite o número de tentativas. Respostas 4xx que não sejam 429 não devem ser repetidas — corrija a requisição.
Limites de requisições. Ao receber 429, aguarde a quantidade de segundos indicada no cabeçalho Retry-After antes de tentar de novo. Não repita a requisição na hora.
Validação. Em 402402 VALIDATION_ERROR, espere encontrar em error.detail o detalhamento por campo. Mostre essas mensagens ao usuário para que ele possa corrigir os dados.
Logs. Registre error.code, e não error.message, para alertas e análises: os códigos são estáveis, as mensagens não.