Erros

Toda requisição com falha retorna um status fora da faixa 2xx e um corpo JSON com este formato:

{
  "error": {
    "code": "not_found",
    "message": "Order \"1042\" not found.",
    "doc_url": "https://www.clakta.com/docs/api-reference/errors#not-found",
    "type": "order_not_found"
  }
}

• code — um identificador estável e legível por máquina. Use-o para ramificar sua lógica, nunca a message.
• message — uma explicação legível por humanos, destinada aos seus logs. O texto pode mudar a qualquer momento.
• doc_url — um link para a seção correspondente nesta página.
• type — um identificador estável da falha específica, presente quando se aplica. É mais preciso que code (vários type mapeiam para um mesmo code) e é o que nossa própria interface usa para localizar as mensagens.

Códigos de erro

bad_request

400 — A requisição está malformada e a API não conseguiu processá-la. As causas mais comuns são a ausência do prefixo Bearer no cabeçalho Authorization, um corpo JSON inválido ou a falta de um identificador obrigatório como orderId. Corrija a requisição; repeti-la sem alterações falhará de novo.

unauthorized

401 — A autenticação falhou. O cabeçalho Authorization está ausente, ou a chave de API está malformada ou foi revogada. Verifique se o cabeçalho está no formato Bearer <chave> e se a chave continua ativa em Configurações → Chaves de API.

forbidden

403 — A chave de API é válida, mas não tem permissão para esta operação, por falta do escopo exigido ou porque o usuário não tem o cargo necessário. Conceda o escopo indicado na página do endpoint e tente novamente.

exceeded_limit

403 — A ação excederia um limite do plano da sua equipe, como a cota mensal de pedidos. A mensagem informa qual limite foi atingido. Faça upgrade do plano ou aguarde o próximo ciclo de cobrança.

not_found

404 — O recurso solicitado não existe, ou sua chave de API não pode acessá-lo. A API responde 404 em vez de 403 para recursos fora do seu acesso, de modo que nunca confirma a existência de algo. Verifique o identificador e o projeto ao qual a chave tem acesso.

conflict

409 — A requisição conflita com o estado atual do recurso. A causa habitual é criar um pedido com um orderId que já existe no projeto. Trate como "já registrado" em vez de repetir a requisição.

invite_pending

409 — Já existe um convite pendente para este e-mail. Reenvie ou revogue o convite existente em vez de criar um segundo.

invite_expired

410 — O convite expirou e não pode mais ser aceito. Emita um novo convite.

unprocessable_entity

422 — A requisição está bem formada, mas falhou na validação. A message indica o campo problemático e o que estava errado, por exemplo um e-mail fora do RFC 5322, um telefone fora do padrão E.164 ou um preço negativo. Corrija o payload e tente novamente.

rate_limit_exceeded

429 — Você excedeu a cota de requisições do seu plano no minuto atual. Este é o único erro que vale repetir automaticamente: aguarde o intervalo informado em Retry-After e faça backoff exponencial. O X-RateLimit-Reset indica quando a janela reinicia.

internal_server_error

500 — Algo falhou do nosso lado. A resposta não expõe a causa deliberadamente. Esses erros são reportados automaticamente ao nosso monitoramento; tente novamente com backoff e contate support@clakta.com se persistir.

meta_api_error

500 — Uma chamada à API de Marketing da Meta falhou ao atender sua requisição. Geralmente é transitório, ou a conta de anúncio conectada precisa ser reautorizada em Gerenciador de anúncios.

google_ads_api_error

500 — Uma chamada à API do Google Ads falhou ao atender sua requisição. Geralmente é transitório, ou a conta de anúncio conectada precisa ser reautorizada em Gerenciador de anúncios.

tiktok_api_error

500 — Uma chamada à API de Marketing do TikTok falhou ao atender sua requisição. Geralmente é transitório, ou a conta de anúncio conectada precisa ser reautorizada em Gerenciador de anúncios.

Boas práticas ao tratar erros

• Ramifique pelo code, não pela message. Mensagens são texto e vão mudar.
• Repita apenas o que é repetível. 429 e 5xx merecem backoff exponencial; códigos 4xx descrevem uma requisição inválida e falharão igual na repetição.
• Torne as escritas idempotentes. Envie um orderId estável para que uma repetição após timeout de rede apareça como conflict em vez de criar um pedido duplicado.
• Registre doc_url e type. Eles identificam a falha específica mais rápido do que a mensagem.