Erros

Como ler um erro#

Há dois formatos:

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

{ "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:

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. 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#

Idempotência#

Validação e regras gerais#

Pix#

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.

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

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.

Nota 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.

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:

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.

Internacional (Paycore)#

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.

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. Eles são sinais de tela e nunca substituem o webhook.