Tratar erros da API

HTTP	Significado	Ação do cliente
400	O processador rejeitou a operação e o Gateway traduziu a falha.	Registre o corpo e não repita sem entender a causa.
401	O token está ausente, inválido ou sem acesso.	Corrija a credencial e remova `Origin` das chamadas entre servidores.
403	A operação não está disponível para o tipo de estabelecimento.	Não repita sem alterar o credenciamento.
404	O recurso ou a configuração consultada não existe no escopo autenticado.	Confirme o identificador e o processador.
409	O domínio ou o processador detectou um conflito.	Consulte a transação antes de criar outra.
422	Um campo é inválido ou uma capacidade Pix não está disponível.	Corrija os dados ou a configuração indicada.
429	O limite da rota foi excedido.	Espere e aplique recuo antes de tentar novamente.
500	Uma falha interna ou não traduzida interrompeu a operação.	Consulte pelo identificador do estabelecimento antes de repetir uma escrita.

HTTP

Significado

Ação do cliente

400

O processador rejeitou a operação e o Gateway traduziu a falha.

Registre o corpo e não repita sem entender a causa.

401

O token está ausente, inválido ou sem acesso.

Corrija a credencial e remova Origin das chamadas entre servidores.

403

A operação não está disponível para o tipo de estabelecimento.

Não repita sem alterar o credenciamento.

404

O recurso ou a configuração consultada não existe no escopo autenticado.

Confirme o identificador e o processador.

409

O domínio ou o processador detectou um conflito.

Consulte a transação antes de criar outra.

422

Um campo é inválido ou uma capacidade Pix não está disponível.

Corrija os dados ou a configuração indicada.

429

O limite da rota foi excedido.

Espere e aplique recuo antes de tentar novamente.

500

Uma falha interna ou não traduzida interrompeu a operação.

Consulte pelo identificador do estabelecimento antes de repetir uma escrita.

Erro de validação

{
  "message": "The given data was invalid.",
  "errors": {
    "amount": [
      "The amount field is required."
    ]
  }
}

Falhas tratadas pelo Handler usam o envelope error, com o código repetido em status. O valor de message pode ser texto ou um mapa de campos.

{
  "error": {
    "message": {
      "base": [
        "Pix processor not found."
      ]
    },
    "status": 422
  }
}

O endpoint de reembolso captura erros do processador dentro do próprio controller. Nessa operação específica, HTTP 422 e HTTP 500 usam um corpo simples com message, conforme os exemplos da referência.

Repetir uma escrita

Antes de repetir uma criação após timeout ou HTTP 500, consulte a transação pelo merchant_transaction_id. Uma falha de transporte não prova que a primeira tentativa não produziu efeito.

Em report_financial_info, o corpo recebe timestamp, mas um erro de validação de data pode usar a chave external_timestamp.

Primeiros passos

Pagamentos

Webhooks

Tratar erros da API

Erro de validação

Repetir uma escrita

​Erro de validação

​Repetir uma escrita

Erro de validação

Repetir uma escrita