Pular para o conteúdo

↑↓ navegar ↵ abrir Ctrl↵ nova aba esc fechar
CódigoSignificado
200Sucesso (GET, PATCH, batch)
201Transação criada (POST single)
401Credenciais ausentes ou inválidas
403Empresa bloqueada, ou nenhum produto que usa transação ativo (só na criação)
404Transação ou merchant não encontrado
405Transações não podem ser apagadas (DELETE), ver Deletar transação
409Conflito (duplicata, ou atualização de transação imutável)
422Erro de validação (campos inválidos)
429Muitas requisições (limite: 100 por minuto por IP)
500Erro interno do servidor

Todas as respostas de erro seguem o mesmo formato:

{
"error": {
"code": "ERROR_CODE",
"message": "Descrição do erro"
}
}

CódigoHTTPMensagem
UNAUTHORIZED401Missing or invalid Authorization header
UNAUTHORIZED401Invalid Basic Auth format
UNAUTHORIZED401Missing client_id or client_secret
UNAUTHORIZED401Invalid credentials
COMPANY_BLOCKED403Company is blocked
CódigoHTTPMensagem
VALIDATION_ERROR422Mensagem do validador (ex: card_last4 must be exactly 4 digits)
CódigoHTTPMensagem
TRANSACTION_NOT_FOUND404Transaction not found
TRANSACTION_DUPLICATE409Transaction already exists
TRANSACTION_DUPLICATE409Another transaction with this external_source/external_id already exists
TRANSACTION_IMMUTABLE409Transaction cannot be modified: it has been used by a network event
TRANSACTION_DELETE_NOT_ALLOWED405Transactions cannot be deleted
MERCHANT_NOT_FOUND404Merchant not found
PRODUCT_NOT_ACTIVE403Transactions require an active Prevention or Dispute product

PRODUCT_NOT_ACTIVE só aparece na criação (POST /transactions e POST /transactions/batch), quando a empresa não tem Prevenção nem Disputa ativa. Consultar e atualizar não exigem produto ativo. Ver Quem envia transações.

CódigoHTTPMensagem
RATE_LIMIT_EXCEEDED429Rate limit exceeded, retry in X seconds

No endpoint de batch, erros individuais são retornados no array errors dentro de data, sem interromper o processamento das demais transações:

{
"data": {
"created": 1,
"failed": 2,
"results": [
{ "external_id": "TXN-2026-001", "tx_id": "uuid-1", "warnings": [] }
],
"errors": [
{ "index": 1, "external_id": "TXN-2026-002", "status": 409, "error": "Transaction already exists" },
{ "index": 2, "external_id": "TXN-2026-003", "status": 404, "error": "Merchant not found" }
]
}
}

A exceção é o 403 PRODUCT_NOT_ACTIVE: sem Prevenção nem Disputa ativa, a chamada inteira é recusada com 403 e nenhuma transação é criada. Ele não aparece no array errors.

Cada erro inclui:

  • index: posição da linha no array que você enviou, começando em zero.
  • external_id: identifica qual transação falhou.
  • status: código HTTP equivalente do erro.
  • error: mensagem descritiva.