Códigos de erro

Códigos HTTP

Código	Significado
200	Sucesso (GET, PATCH, batch)
201	Transação criada (POST single)
204	Transação deletada (DELETE)
401	Credenciais ausentes ou inválidas
403	Empresa bloqueada
404	Transação ou merchant não encontrado
409	Conflito (duplicata ou transação imutável)
422	Erro de validação (campos inválidos)
429	Muitas requisições (limite: 100 por minuto por IP)
500	Erro interno do servidor

---

Formato das respostas de erro

Todas as respostas de erro seguem o mesmo formato:

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

---

Códigos de erro possíveis

Autenticação

Código	HTTP	Mensagem
UNAUTHORIZED	401	Missing or invalid Authorization header
UNAUTHORIZED	401	Invalid Basic Auth format
UNAUTHORIZED	401	Missing client_id or client_secret
UNAUTHORIZED	401	Invalid credentials
COMPANY_BLOCKED	403	Company is blocked

Validação

Código	HTTP	Mensagem
VALIDATION_ERROR	422	Mensagem do validador (ex: card_last4 must be exactly 4 digits)

Transações

Código	HTTP	Mensagem
TRANSACTION_NOT_FOUND	404	Transaction not found
TRANSACTION_DUPLICATE	409	Transaction already exists
TRANSACTION_DUPLICATE	409	Another transaction with this external_source/external_id already exists
TRANSACTION_IMMUTABLE	409	Transaction cannot be modified: it has been used by a network event
MERCHANT_NOT_FOUND	404	Merchant not found

Rate limit

Código	HTTP	Mensagem
RATE_LIMIT_EXCEEDED	429	Rate limit exceeded, retry in X seconds

---

Erros no envio em lote

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" }
    ]
  }
}

Cada erro inclui:

• external_id: identifica qual transação falhou.
• status: código HTTP equivalente do erro.
• error: mensagem descritiva.