Error Handling

Last updated: 2026-10-20

HTTP Status Codes

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

CodeMeaning
200 OKRequest succeeded.
201 CreatedResource was successfully created (e.g. a payment request was submitted).
400 Bad RequestThe request was malformed or validation failed. Check your request body and parameters.
401 UnauthorizedAuthentication failed. Ensure your bearer token and subscription key are valid and not expired.
404 Not FoundThe requested resource could not be found (e.g. unknown terminal ID or reference).
409 ConflictA conflict occurred, such as a duplicate reference ID.
422 Unprocessable EntityThe server understood the request but could not process it due to semantic errors in the payload.
429 Too Many RequestsThe request was throttled. Wait for Retry-After when supplied, then retry with backoff and jitter.
500 Internal Server ErrorAn unexpected error occurred on the server. Retry after a short delay.

Error Codes

Error CodeDescription
WP01Terminal not linked to a terminal ID
WP02Terminal not found
WP03Merchant inactive
WP04Transaction not found
WP05Unique constraint exception
WP06Reference constraint exception
WP07Cannot insert null exception
WP08Internal server error
WP09Terminal is busy processing another transaction
WP10Unable to generate a unique registration code. Try later! serialNo:
WP11Given serial number is already linked to a terminal ID
WP12No terminal found in Unlinked state for given registration code
WP13No record found for Terminal Id
WP14No record found for Merchant Id
WP15Merchant not active
WP16Specified terminal does not belong to the merchant
WP17None(Unknown)
WP18No transaction is processing currently in the specified terminal
WP19Error while generating JWT Token
WP20MerchantID cannot be null or empty
WP21TerminalID cannot be null or empty
WP22PaymentMethod recieved from ECR is invalid
WP23No SignalR connection found for the terminal
WP24Failed sending SignalR notification to terminal
WP25Acknowledgement timed-out from terminal
WP26Only 30 days of data is allowed to retrieve
WP27Only past 90 days data is availble to retrieve
WP28Database concurrency issue
WP29One or more required fields missing
WP30Terminal has acknowledged the previous transaction, but it has not send a response. Hence user may cancel the previous transaction if its timed-out
WP31Transaction is not in a valid state
WP32Token validity period should be greater than 0
WP33Terminal is already linked to a serial number
WP34No print request found with Id
WP35No 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 HTTP 429, retryable 5xx, and network failures, use bounded exponential backoff with jitter. Honor Retry-After when the response provides it. For example:

  1. Wait 1 second, retry.
  2. Wait 2 seconds, retry.
  3. Wait 4 seconds, retry.
  4. Cap the delay at 30 seconds and stop after the application's retry/time budget.
  5. Preserve the transaction reference and alert your on-call engineer if the result remains unknown.

Do not retry other 4xx errors automatically. Correct the request, credentials, or ECR state first.

Never assume that a timed-out financial POST failed. Reconcile its outcome using the stored onlineAPIRefId or the documented last-transaction recovery flow before allowing a replacement transaction.