Error codes
HTTP codes
Section titled “HTTP codes”| Code | Meaning |
|---|---|
| 200 | Success (GET, PATCH, batch) |
| 201 | Transaction created (single POST) |
| 401 | Missing or invalid credentials |
| 403 | Company blocked, or no product that uses transactions is active (creation only) |
| 404 | Transaction or merchant not found |
| 405 | Transactions cannot be deleted (DELETE), see Delete transaction |
| 409 | Conflict (duplicate, or update of an immutable transaction) |
| 422 | Validation error (invalid fields) |
| 429 | Too many requests (limit: 100 per minute per IP) |
| 500 | Internal server error |
Error response format
Section titled “Error response format”Every error response follows the same format:
{ "error": { "code": "ERROR_CODE", "message": "Error description" }}Possible error codes
Section titled “Possible error codes”Authentication
Section titled “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
Section titled “Validation”| Code | HTTP | Message |
|---|---|---|
VALIDATION_ERROR | 422 | Validator message (e.g. card_last4 must be exactly 4 digits) |
Transactions
Section titled “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 |
TRANSACTION_DELETE_NOT_ALLOWED | 405 | Transactions cannot be deleted |
MERCHANT_NOT_FOUND | 404 | Merchant not found |
PRODUCT_NOT_ACTIVE | 403 | Transactions require an active Prevention or Dispute product |
PRODUCT_NOT_ACTIVE only shows up on creation (POST /transactions and POST /transactions/batch), when the company has neither Prevention nor Dispute active. Retrieving and updating do not require an active product. See Who sends transactions.
Rate limit
Section titled “Rate limit”| Code | HTTP | Message |
|---|---|---|
RATE_LIMIT_EXCEEDED | 429 | Rate limit exceeded, retry in X seconds |
Errors in batch upload
Section titled “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" } ] }}The exception is 403 PRODUCT_NOT_ACTIVE: without an active Prevention or Dispute, the whole call is refused with 403 and no transaction is created. It does not show up in the errors array.
Each error includes:
index: position of the row in the array you sent, starting at zero.external_id: identifies which transaction failed.status: the equivalent HTTP code of the error.error: descriptive message.