> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atriby.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Solução de problemas

> Erros comuns ao integrar pedidos, UTMs, webhooks e tokens.

## 401 UNAUTHORIZED

O token está ausente, inválido ou foi enviado sem o formato bearer.

Confira:

```http theme={null}
Authorization: Bearer atb_live_...
```

## 403 TOKEN\_REVOKED

O token existiu, mas foi revogado. Crie um novo token em `/integracoes?tab=tokens` e atualize a variável de ambiente do seu backend.

## 400 VALIDATION\_FAILED

O payload não passou na validação. Causas comuns:

* Data sem timezone.
* Valor monetário enviado como float.
* Produto sem `name`, `quantity` ou `unitPriceCents`.
* Campos desconhecidos em locais estritos do payload.

Use datas como:

```text theme={null}
2026-05-10T15:34:14Z
2026-05-10T12:34:14-03:00
```

## Pedido duplicado

`409 DUPLICATE_EXTERNAL_ID` indica que o mesmo `externalId` já existe para o dashboard. Se a chamada era retry do mesmo pedido, use `Idempotency-Key` desde a primeira tentativa.

## Transição de status inválida

`422 INVALID_STATUS_TRANSITION` ocorre quando o pedido tenta sair de um estado terminal ou fazer uma transição não suportada. Exemplo: `chargedback -> paid` não é permitido.

## UTM não propagou

Verifique:

* O script carregou antes do clique.
* A página recebeu UTMs na URL de entrada.
* O link de checkout é `http` ou `https`.
* `data-checkout-domains` não restringiu o domínio errado.
* O link não tinha valores próprios para os mesmos parâmetros, porque link-wins preserva o valor existente.

## Webhook falhando

Confira:

* Endpoint público acessível via HTTP/HTTPS.
* Tempo de resposta abaixo do timeout.
* Resposta HTTP 2xx.
* Validação correta de HMAC usando raw body.
* Uso de `x-atriby-delivery` para deduplicar retries manuais.

## Token perdido

O token completo não pode ser reexibido. Crie um novo token, atualize seu backend e revogue o antigo.

## Setup local

Usuários finais normalmente não precisam rodar a Atriby localmente. Se você é desenvolvedor do projeto e precisa de setup local, procure o repositório interno ou fale com o suporte.