# Erros

> Cada código de erro da API: status, causa, o que fazer e se pode repetir.

Fonte: https://app.thronecorporate.com/docs/errors

## Como ler um erro

Há dois formatos:

```json
{ "error": "invalid_amount", "message": "Valor abaixo do mínimo aceito: CHF 0,80." }
```

```json
{ "message": "O campo customer.email é obrigatório.", "errors": { "customer.email": ["O campo customer.email é obrigatório."] } }
```

O primeiro é erro de regra: decida pelo campo `error`, que é fixo. O segundo é erro de campo (validação), com a lista em `errors`. O texto de `message` serve para log e apoio e pode mudar.

Alguns erros trazem campos extras, sempre como acréscimo:

| Campo | Onde aparece | Para que serve |
|---|---|---|
| `retryable` | `502` e `503` do cartão | `true`: vale repetir com uma `Idempotency-Key` nova. `false`: não repita igual |
| `retry_same_key` | `502 acquirer_error` do Pix em `POST /transactions` | Só vem com `true`: a cobrança pode ter sido criada. Repita a mesma chamada, com a mesma `Idempotency-Key` e o mesmo corpo, e nunca com uma chave nova |
| Header `Retry-After` | `429`, `503` e `fx_unavailable` | Segundos que você deve esperar antes de repetir |
| `max_amount_cents`, `min_amount_cents`, `currency` | `422 invalid_amount` do cartão | O limite da adquirente, na moeda que você mandou |
| `alternatives` | `422 invalid_amount` acima do máximo | Outras adquirentes habilitadas na conta que aceitam o valor |
| `field` | `422 invalid_appearance` do Checkout Brasil | O caminho da chave de `appearance` recusada, por exemplo `appearance.button.text` |

## Repetir ou não

A regra única de repetição, com o que a API devolve em cada caso, está em [como repetir com segurança](/docs/comecar#como-repetir-uma-chamada-com-seguranca). Em resumo:

- **`4xx`**: nada foi criado. Corrija o que for preciso e, se for repetir, use uma `Idempotency-Key` **nova**. Repetir a mesma chave devolve `409`.
- **`502` ou `503` com o JSON da API**: nada foi criado. Repita com uma `Idempotency-Key` **nova**, depois do `Retry-After` quando ele vier. No `502` do cartão, só com `"retryable": true`.
- **`502 acquirer_error` com `"retry_same_key": true`** (só no Pix de `POST /transactions`): é a exceção da linha acima. A cobrança pode ter sido criada na adquirente. Repita a **mesma** chamada, com a mesma `Idempotency-Key` e o mesmo corpo da primeira tentativa: a chave fica livre para essa repetição, e só para ela. Com outro corpo, a resposta é `422 idempotency_key_mismatch`. Nunca use uma chave nova para esse pedido, porque ela pode gerar uma segunda cobrança.
- **`500`**: algo pode ter sido criado. Não use uma `Idempotency-Key` nova antes de conferir no painel. Em `POST /elements/checkout`, repita antes a mesma chamada, igual: se nada foi criado, ela roda de novo.
- **Sem resposta (falha de conexão, timeout ou resposta sem o JSON da API)**: repita a **mesma** chamada, com a mesma `Idempotency-Key` e o mesmo corpo.
- **`409 idempotency_key_processing`**: a primeira chamada ainda está em andamento. Espere alguns segundos e repita igual. Se continuar por mais de 2 minutos, confira no painel se algo foi criado antes de usar uma chave nova.

A coluna **Repetir** das tabelas abaixo diz o que fazer em cada código.

## Autenticação e permissões

| Status | `error` | Significado | O que fazer | Repetir |
|---|---|---|---|---|
| `401` | `unauthorized`, `detail: credentials_required` | Faltou o header `Authorization` ou ele não começa com `Bearer ` | Envie `Authorization: Bearer pk:sk` | Depois de corrigir |
| `401` | `unauthorized`, `detail: malformed_credentials` | Formato errado (por exemplo, base64) | Envie `pk:sk` em texto | Depois de corrigir |
| `401` | `unauthorized`, `detail: invalid_credentials` | Chave de API inexistente, revogada ou conta bloqueada | Gere outra chave de API no painel | Depois de corrigir |
| `401` | `unauthorized`, `detail: ip_not_allowed` | IP fora da lista de IPs da chave de API | Inclua o IP na lista da chave | Depois de corrigir |
| `403` | `scope_required` | A chave não tem a permissão do endpoint | Veja `required_scope` e ligue a permissão | Com chave nova |
| `403` | `withdrawal_ip_not_authorized` | IP fora da lista de IPs de saque | Cadastre o IP do servidor nos IPs de saque | Com chave nova |
| `403` | `seller_not_approved` | A conta ainda não está liberada para operar | Conclua o cadastro no painel | Com chave nova |

## Idempotência

| Status | `error` | Significado | O que fazer | Repetir |
|---|---|---|---|---|
| `400` | `idempotency_key_required` | Faltou o header `Idempotency-Key` ou ele não tem de 8 a 128 caracteres | Envie um UUID v4 por operação | Depois de corrigir |
| `422` | `idempotency_key_mismatch` | Mesma `Idempotency-Key` com corpo diferente | Use uma `Idempotency-Key` nova | Com chave nova |
| `422` | `idempotency_key_other_endpoint` | Mesma `Idempotency-Key` usada em outro endpoint (o `POST /elements/checkout` e o `POST /elements/checkout/br` não compartilham chave) | Use uma `Idempotency-Key` nova | Com chave nova |
| `409` | `idempotency_key_processing` | A primeira chamada ainda está em andamento, ou terminou em erro de servidor (`5xx`) e a chave ficou presa por até 24 horas (em `POST /elements/checkout`, um `502` ou `503` libera a chave; um `500` também, a não ser que a venda tenha chegado a ser criada ou que a chamada tenha sido interrompida no servidor; em `POST /transactions`, o `502 acquirer_error` também libera a chave, e com `"retry_same_key": true` só para a repetição do mesmo corpo) | Espere alguns segundos e repita a mesma chamada, igual. Se continuar por mais de 2 minutos, siga a [regra de repetição](/docs/comecar#como-repetir-uma-chamada-com-seguranca) | A mesma chamada, igual |
| `409` | `idempotency_key_race` | Chamadas simultâneas com a mesma `Idempotency-Key`, ou uma chave cuja primeira chamada recebeu erro `4xx` | Depois de um `4xx`, nada foi criado: use uma `Idempotency-Key` nova. Se foram duas chamadas ao mesmo tempo, espere alguns segundos e repita a mesma chamada, igual: ela devolve a resposta da primeira | Com chave nova depois de um `4xx`. A mesma chamada, igual, depois de chamadas simultâneas |
| `409` | `idempotency_key_in_use` | Essa `Idempotency-Key` não pode ser usada pela sua conta | Use uma `Idempotency-Key` nova | Com chave nova |

## Validação e regras gerais

| Status | `error` | Significado | O que fazer | Repetir |
|---|---|---|---|---|
| `422` | (lista em `errors`) | Campo faltando ou fora do formato | Corrija o campo indicado | Com chave nova |
| `422` | `invalid_request` | Regra de valor, método ou destino (por exemplo, Pix abaixo de R$ 1,00 ou saque abaixo do mínimo) | Leia o `message` e ajuste | Com chave nova |
| `404` | | O recurso não existe ou não é da sua conta | Confira o id (UUID em minúsculas) | Depois de corrigir |
| `429` | `rate_limit_exceeded` | Mais de 10 cobranças Pix por segundo | Respeite o `Retry-After` | Com chave nova, depois do `Retry-After` |
| `429` | | Mais de 10 chamadas por segundo sem credencial válida, do mesmo IP | Corrija a credencial e respeite o `Retry-After` | Depois do `Retry-After` |
| `503` | `temporarily_unavailable` | Falha temporária. Nada foi criado | Respeite o `Retry-After`, com recuo ([como](/docs/limites#quando-a-resposta-e-429-ou-503)) | Com chave nova, depois do `Retry-After` |

## Pix

| Status | `error` | Significado | O que fazer | Repetir |
|---|---|---|---|---|
| `422` | `pix_not_enabled` | O recebimento por Pix não está habilitado nesta conta. Nada foi criado. Vale para `POST /transactions` com `pix` e para `POST /payment-links` | Fale com o suporte para habilitar. Cartão e saques por Pix continuam normais | Não, até habilitar |
| `422` | `items_total_mismatch` | A soma dos itens não bate com `amount_cents` | Corrija os itens ou o valor | Com chave nova |
| `422` | `split_invalid` | Divisão para a própria conta | Remova essa divisão | Com chave nova |
| `502` | `acquirer_error`, com `"retry_same_key": true` | A adquirente não confirmou o Pix, e a cobrança pode ter sido criada. Nada fica gravado na sua conta e a chave é liberada para a repetição do mesmo corpo | Repita a mesma chamada, com a mesma `Idempotency-Key` e o mesmo corpo da primeira tentativa. Se o erro continuar, fale com o suporte informando a chave, antes de criar outra cobrança para o pedido | A mesma chamada, igual |
| `502` | `acquirer_error`, sem `retry_same_key` | A adquirente recusou o Pix antes de criar. Nada foi criado | Tente de novo em instantes | Com chave nova |
| `409` | `already_revoked` | O link de pagamento já estava desativado | Nada a fazer | Não |

## Cartão, integração direta na Vortex

Só em `POST /api/v1/vault/vortex/cards` e `POST /api/v1/vortex/payments`. Veja [Server-to-server na Vortex](/docs/cartao/vortex-direto).

| Status | `error` | Significado | O que fazer | Repetir |
|---|---|---|---|---|
| `422` | `partner_api_not_enabled` | A integração direta da Vortex não está liberada na conta. A liberação é por adquirente: a da Eminence não vale aqui | Fale com o suporte | Com a mesma chave, depois da liberação |
| `422` | `invalid_card` | Número, validade, CVV ou nome do titular inválidos. O campo `field` diz qual | Peça ao comprador para conferir o cartão | Com chave nova, depois de corrigir |
| `422` | `invalid_card_token` | O `card_token` está fora do formato, venceu ou já foi usado. Ele serve para uma cobrança só | Tokenize de novo | Com chave nova |
| `422` | `fx_unavailable` | Cotação momentaneamente indisponível. Nada foi criado | Espere o `Retry-After` (60 s) | Com a mesma chave |
| `422` | `amount_out_of_range` | Valor fora da faixa da adquirente. A resposta traz `min_amount_cents`, `max_amount_cents` e `currency`, na moeda que você enviou | Ajuste o valor | Com chave nova |
| `503` | `busy` | Cobranças diretas demais em andamento ao mesmo tempo. Nada foi criado | Espere o `Retry-After` | Com a mesma chave |
| `422` | `invalid_cycle` | Só na integração direta da Vortex: o `recurrence.cycle` não é um dos sete ciclos aceitos. A resposta traz a lista. Nada foi criado | Mande um de `weekly`, `biweekly`, `monthly`, `bimonthly`, `quarterly`, `semiannually` ou `yearly` | Com a mesma chave, depois de corrigir |
| `422` | `recurrence_not_supported` | Só na integração direta da Vortex: o corpo trouxe `recurrence` e a cobrança recorrente não está disponível nesta adquirente no momento. Nada foi criado | Fale com o suporte, ou cobre sem o campo | Com a mesma chave, depois da liberação |
| `422` | `one_click_not_supported` | O corpo trouxe `one_click_from` numa rota que não tem esse campo. Nada foi criado | Na Vortex, o upsell em um clique tem rota própria: [`POST /api/v1/vortex/upsell`](/docs/cartao/vortex-direto#upsell-em-um-clique). Nas outras, cobre normalmente | Com a mesma chave, sem o campo |

## Cartão (Sterling, Imperium, NovaCorp, Eminence, Apex, ShadowBank, Vortex)

| Status | `error` | Significado | O que fazer | Repetir |
|---|---|---|---|---|
| `422` | `card_not_enabled` | A conta não tem cartão habilitado | Fale com o suporte | Não |
| `422` | `invalid_acquirer` | `acquirer` fora da lista | Use `sterling`, `imperium`, `novacorp`, `eminence`, `apex`, `shadowbank` ou `vortex` | Com chave nova |
| `422` | `acquirer_not_enabled` | A adquirente pedida em `acquirer` não está habilitada na conta. Em `POST /elements/checkout/br`, também quando a conta não tem adquirente habilitada para o Checkout Brasil, ou quando `acquirer` pede uma que não atende o Checkout Brasil | Escolha uma das listadas no `message` (ou em `GET /elements/acquirers`). No Checkout Brasil, fale com o suporte para habilitar | Com chave nova |
| `422` | `customer_required_for_shadowbank` | Só na ShadowBank: a criação veio sem `customer.name` ou `customer.email`, com e-mail inválido ou fora dos tamanhos (`name` até 120 caracteres, `email` até 180). Nada foi criado | Mande os dois campos na criação, dentro dos tamanhos. O elemento não pergunta nome nem e-mail ao comprador; colete os dois na sua página | Com chave nova, depois de corrigir |
| `422` | `customer_required_for_vortex` | Só na Vortex: a criação veio sem `customer.name` ou `customer.email`, com e-mail inválido ou fora dos tamanhos (`name` até 120 caracteres, `email` até 180). Nada foi criado | Mande os dois campos na criação, dentro dos tamanhos. O elemento não pergunta nome nem e-mail ao comprador; colete os dois na sua página | Com chave nova, depois de corrigir |
| `422` | `currency_not_supported` | Moeda fora das 48 aceitas | Use uma moeda da [lista](/docs/cartao/moeda#moedas-aceitas) | Com chave nova |
| `422` | `fx_unavailable` | Cotação momentaneamente indisponível | Espere o `Retry-After` (60 s) | Com chave nova |
| `422` | `invalid_amount` | Valor abaixo do mínimo ou acima do máximo da adquirente, na moeda enviada e pela cotação do dia. A resposta traz o limite na sua moeda (`min_amount_cents` ou `max_amount_cents`) e, acima do máximo, `alternatives` | Abaixo do mínimo, aumente o valor. Acima do máximo, crie com o `acquirer` de uma das `alternatives` ou divida o pedido | Não com o mesmo valor na mesma adquirente |
| `422` | `invalid_cycle` | O `recurrence.cycle` não é um dos sete ciclos aceitos. A resposta traz a lista. Nada foi criado | Mande um de `weekly`, `biweekly`, `monthly`, `bimonthly`, `quarterly`, `semiannually` ou `yearly` | Com chave nova, depois de corrigir |
| `422` | `recurrence_not_supported` | A adquirente da chamada não faz cobrança recorrente. Nada foi criado | Mande `acquirer` com uma das que o `message` lista | Com chave nova, depois de corrigir |
| `422` | `field_not_supported` | Só em `POST /elements/checkout/br`: o corpo trouxe `one_click_from` ou `recurrence`, que não existem no Checkout Brasil. Nada foi criado | Tire o campo do corpo. Para upsell em um clique e recorrência, use o `POST /elements/checkout` | Com chave nova, depois de corrigir |
| `422` | `invalid_appearance` | Só em `POST /elements/checkout/br`: o objeto `appearance` trouxe chave que não existe, valor fora da regra ou combinação impossível. O campo `field` diz qual chave. Nada foi criado | Corrija a chave indicada em `field` | Com chave nova, depois de corrigir |
| `503` | `temporarily_unavailable` | A adquirente está em pausa, instável ou sem capacidade. Vem com `Retry-After` e `"retryable": true`. Nada foi criado | Espere o `Retry-After`, ou crie com outra adquirente habilitada | Com chave nova, depois do `Retry-After` |
| `502` | `checkout_failed` | O checkout não foi criado. `"retryable": false` quando a adquirente recusou a criação; `true` numa falha passageira de conexão | Com `false`, não repita igual e fale com o suporte se continuar. Com `true`, repita | Só com `"retryable": true`, com chave nova |

O máximo por venda depende da adquirente e varia com a moeda e com a cotação do dia. `GET /elements/acquirers?currency=` mostra o limite atual na moeda pedida. Veja [Escolher a adquirente](/docs/cartao/escolher#quando-o-valor-passa-do-maximo).

> [!NOTE]
> O campo `one_click_from` não tem erro próprio. Venda de origem inexistente, de outra conta, não paga, fora da janela ou acima do teto não devolve `4xx`: a resposta vem `201` com `one_click: false` e o comprador digita o cartão. Veja [Upsell em um clique](/docs/cartao/oneclick).

Os endpoints de recorrência (`GET /recurrences`, `GET /recurrences/{id}` e `POST /recurrences/{id}/cancel`) usam o mesmo formato de erro e têm um código próprio, no cancelamento:

| Status | `error` | Significado | O que fazer | Repetir |
|---|---|---|---|---|
| `422` | `cancel_failed` | Esta recorrência não é cancelada pela API. Ela continua valendo | Fale com o suporte | Não |
| `503` | `cancel_failed` | O cancelamento não foi confirmado agora | Repita a mesma chamada em instantes, até receber `200`. Enquanto a resposta não for `200`, trate a recorrência como ativa | A mesma chamada, igual |

Uma recorrência que não é da sua conta responde `404`, como qualquer outro recurso. Os detalhes de cada situação estão em [Recorrência](/docs/cartao/recorrencias).

## Internacional (Paycore)

| Status | `error` | Significado | O que fazer | Repetir |
|---|---|---|---|---|
| `422` | `global_not_enabled` | O Internacional não está habilitado | Fale com o suporte | Não |
| `422` | `unsupported_currency` | Moeda fora das 22 aceitas | Veja o campo `supported` | Com chave nova |
| `422` | `currency_not_enabled` | Moeda não liberada na sua conta | Veja o campo `enabled` | Com chave nova |
| `422` | `amount_too_small` | Abaixo do mínimo | Veja o campo `minimum` | Com chave nova |

## Saques

O saque por Pix não depende do recebimento por Pix: uma conta com `pix_not_enabled` na criação de cobrança continua sacando normalmente.

| Status | `error` | Significado | O que fazer | Repetir |
|---|---|---|---|---|
| `401` | `invalid_two_factor` | Código do autenticador errado ou vencido, ou o dono da conta não tem 2FA ativado | Gere um código novo; se continuar, confira o 2FA no painel | Com chave nova e código novo |
| `422` | `insufficient_balance` | Saldo menor que `amount_cents` | Consulte `GET /balance` | Com chave nova |
| `429` | `daily_limit_exceeded` | Passou do limite diário da conta | Tente no dia seguinte | Com chave nova, no dia seguinte |
| `429` | `rate_limited` | Mais de 1 pedido de saque por minuto | Espere 60 segundos | Com chave nova |

## Eventos de erro do checkout embutido

Os códigos que chegam em `throne-elements:error` (`e.detail.code`, como `declined` e `popup_blocked`) estão em [Throne Elements](/docs/cartao/elements#codigos-de-erro). Eles são sinais de tela e nunca substituem o webhook.