Error Handling

Last updated: 2023-06-30

HTTP Status Codes

The Online API uses standard HTTP status codes to indicate the outcome of a request.

Code	Meaning
`200 OK`	Request succeeded.
`201 Created`	Resource was successfully created (e.g. a payment request was submitted).
`400 Bad Request`	The request was malformed or validation failed. Check your request body and parameters.
`401 Unauthorized`	Authentication failed. Ensure your bearer token and subscription key are valid and not expired.
`404 Not Found`	The requested resource could not be found (e.g. unknown terminal ID or reference).
`409 Conflict`	A conflict occurred, such as a duplicate reference ID.
`422 Unprocessable Entity`	The server understood the request but could not process it due to semantic errors in the payload.
`500 Internal Server Error`	An unexpected error occurred on the server. Retry after a short delay.

Error Codes

Error Code	Description
`WP01`	`Terminal not linked to a terminal ID`
`WP02`	`Terminal not found`
`WP03`	`Merchant inactive`
`WP04`	`Transaction not found`
`WP05`	`Unique constraint exception`
`WP06`	`Reference constraint exception`
`WP07`	`Cannot insert null exception`
`WP08`	`Internal server error`
`WP09`	`Terminal is busy processing another transaction`
`WP10`	`Unable to generate a unique registration code. Try later! serialNo:`
`WP11`	`Given serial number is already linked to a terminal ID`
`WP12`	`No terminal found in Unlinked state for given registration code`
`WP13`	`No record found for Terminal Id`
`WP14`	`No record found for Merchant Id`
`WP15`	`Merchant not active`
`WP16`	`Specified terminal does not belong to the merchant`
`WP17`	`None(Unknown)`
`WP18`	`No transaction is processing currently in the specified terminal`
`WP19`	`Error while generating JWT Token`
`WP20`	`MerchantID cannot be null or empty`
`WP21`	`TerminalID cannot be null or empty`
`WP22`	`PaymentMethod recieved from ECR is invalid`
`WP23`	`No SignalR connection found for the terminal`
`WP24`	`Failed sending SignalR notification to terminal`
`WP25`	`Acknowledgement timed-out from terminal`
`WP26`	`Only 30 days of data is allowed to retrieve`
`WP27`	`Only past 90 days data is availble to retrieve`
`WP28`	`Database concurrency issue`
`WP29`	`One or more required fields missing`
`WP30`	`Terminal has acknowledged the previous transaction, but it has not send a response. Hence user may cancel the previous transaction if its timed-out`
`WP31`	`Transaction is not in a valid state`
`WP32`	`Token validity period should be greater than 0`
`WP33`	`Terminal is already linked to a serial number`
`WP34`	`No print request found with Id`
`WP35`	`No print support available for the terminal`

Error Response Format

When an error occurs, the API returns a JSON body with details:

json
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The field 'amount' must be greater than zero.",
  "traceId": "00-abc123-def456-00"
}

Common Error Scenarios

401 Unauthorized

Response
{
   "statusCode": 401,
   "message": "You are not authorized."
}

This occurs when:

The Authorization: Bearer <token> header is missing or contains an expired token.
The Ocp-Apim-Subscription-Key header is missing or incorrect.

Resolution: Re-authenticate to obtain a fresh access token.

400 Bad Request

response
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-987ce5c7034493344e86794d873995e8-ee4c3502d661010a-00",
    "errors": {
      "Amount": [
        "Invalid amount format. Expected format: ##.## or field not present"
      ],
      "TerminalId": [
        "The TerminalId field is required."
      ],
      "CurrencyCode": [
        "Invalid currency code or field not present."
      ]
    }
  }

Typically caused by:

Missing required fields in the request body.
Incorrect data types (e.g. sending a string where a number is expected).
Invalid parameter values (e.g. a negative amount).

Resolution: Review the endpoint documentation for the required parameters and their types.

404 Not Found

Occurs when:

The terminalId or reference does not exist or is not associated with your merchant account.

Resolution: Verify the terminal ID or reference and ensure the terminal is linked to your account.

422 Unprocessable Entity

The request was syntactically valid but could not be processed, for example when a cancel request references a transaction that has already been settled.

Resolution: Check the business rules described in each endpoint's documentation.

Error Response for all other status codes

response
{
  "errorCode": "WP12",
  "message": "No terminal found in Unlinked state for given registration code : 234589",
  "timestamp": "2023-07-04T14:03:59.933704Z"
}

Retry Strategy

For 5xx errors, implement an exponential backoff retry strategy:

Wait 1 second, retry.
Wait 2 seconds, retry.
Wait 4 seconds, retry.
If still failing, alert your on-call engineer.

Do not retry 4xx errors automatically — these indicate a client-side issue that must be fixed before retrying.