Error codes

HTTP codes

Code	Meaning
200	Success (GET, PATCH, batch)
201	Transaction created (single POST)
204	Transaction deleted (DELETE)
401	Missing or invalid credentials
403	Company blocked
404	Transaction or merchant not found
409	Conflict (duplicate or immutable transaction)
422	Validation error (invalid fields)
429	Too many requests (limit: 100 per minute per IP)
500	Internal server error

---

Error response format

Every error response follows the same format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description"
  }
}

---

Possible error codes

Authentication

Code	HTTP	Message
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

Validation

Code	HTTP	Message
VALIDATION_ERROR	422	Validator message (e.g. card_last4 must be exactly 4 digits)

Transactions

Code	HTTP	Message
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

Code	HTTP	Message
RATE_LIMIT_EXCEEDED	429	Rate limit exceeded, retry in X seconds

---

Errors in batch upload

On the batch endpoint, individual errors are returned in the errors array inside data, without stopping the processing of the other transactions:

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

Each error includes:

• external_id: identifies which transaction failed.
• status: the equivalent HTTP code of the error.
• error: descriptive message.