Skip to content

Error Codes ​

System error codes and handling strategies.

Important

These are system error codes, not transaction states. If you receive any error on Confirm or Find requests, do not create a new transaction — retry the same request instead.

Error Code Reference ​

Authentication & Access (1-9) ​

CodeDescriptionAction
1Auth failedCheck credentials in request
2Bad requestCheck request format and retry
5POS sales not activeContact support

Transaction Lookup (20-29) ​

CodeDescriptionAction
20Transaction not foundRetry the request
22External transaction not foundCheck external_transaction_id in request
23Could not get transaction infoRetry the request

Input Validation (50-99) ​

CodeDescriptionAction
50Wrong input dataCheck input data (e.g., phone number format)
60Service provider errorOn Confirm: retry until you get transaction info

Product & Service (100-199) ​

CodeDescriptionAction
101Product is not availableProduct is temporarily inactive
105External transaction id already existsTransaction with this ID already created

Account Validation (200-299) ​

CodeDescriptionAction
201Wrong account numberCheck account number and retry

Balance & Limits (1000-1199) ​

CodeDescriptionAction
1000Transactions limit exceededNot enough balance on account
1001Not enough fundsNot enough balance on account

Customer Restrictions (1200+) ​

CodeDescriptionAction
1200Customer is bannedTransaction cannot be done for this account

Error Response Format ​

Standard Error ​

json
{
  "error": {
    "code": 1001,
    "message": "Not enough funds for this transaction"
  }
}

Error with Display Message ​

When display_error is present, you can show it directly to the customer:

json
{
  "error": {
    "code": 1200,
    "message": "This customer is banned in our system",
    "display_error": "This customer is banned"
  }
}

Retry Strategy ​

When to Retry ​

ScenarioAction
HTTP error (timeout, 5xx)Retry with exponential backoff
Error codes 20, 23, 60Retry the same request
Error on Confirm/FindNever create a new transaction, always retry

Best Practices ​

  1. Always use external_transaction_id — This allows you to safely retry requests without creating duplicates.

  2. On Confirm errors — Keep retrying until you get a valid transaction state. Never create a new transaction.

  3. On Find errors — Retry periodically (every 1-60 minutes) until you receive a final state.

  4. Log all responses — Keep detailed logs for troubleshooting with support.

Contact Support ​

If you consistently encounter the same error:

Paynet API Documentation