Códigos de erro

A API usa os códigos de status HTTP padrão. Em caso de erro, o corpo da resposta traz um JSON com a mensagem — normalmente em message (ou error), e erros de validação com os detalhes por campo.

Códigos de status

Código	Significado	O que fazer
200 OK	Sucesso	—
201 Created	Recurso criado	Use o id retornado
204 No Content	Sucesso sem corpo (ex.: exclusão)	—
400 Bad Request	Requisição malformada	Revise a sintaxe / os parâmetros
401 Unauthorized	Token ausente, inválido ou revogado	Confira o cabeçalho api_access_token — veja Autenticação
403 Forbidden	Autenticado, mas sem permissão (função do usuário, ou recurso não habilitado na conta)	Use um token com a função adequada; para recursos como Kanban, verifique se estão ativos
404 Not Found	Recurso inexistente (ou fora da sua conta)	Confira o id e o account_id do caminho
422 Unprocessable Entity	Validação falhou	Ajuste os campos conforme a mensagem
429 Too Many Requests	Limite de requisições atingido	Reduza a cadência e tente novamente depois
500 Internal Server Error	Erro no servidor	Tente de novo; se persistir, contate o suporte

Exemplo de corpo de erro

{
  "message": "O recurso solicitado não foi encontrado"
}

Erros de validação (422) costumam detalhar os campos:

{
  "message": "Validation failed",
  "errors": {
    "phone_number": ["já está em uso"]
  }
}

Como tratar erros no seu código

• Sempre confira o status HTTP antes de usar o corpo — não assuma sucesso.
• Trate 401/403 como problema de credencial/permissão (não adianta repetir a chamada).
• Trate 429 e 5xx com retry e um backoff (espera crescente entre tentativas).
• Registre a message do corpo — ela costuma dizer exatamente o que corrigir.

const res = await fetch(url, opts)
if (!res.ok) {
  const erro = await res.json().catch(() => ({}))
  throw new Error(`HTTP ${res.status}: ${erro.message ?? "erro desconhecido"}`)
}
const dados = await res.json()