Handling Errors

API Errors

All errors returned by the PaymentExpress API follow a consistent structure. Each error includes an HTTP status code and a JSON body with standardized fields.

Standard Error Format

Every error response contains at least two fields, with an optional third for user-friendly messaging:

• errorCode – A concise identifier for the error type.
• errorMessage – A descriptive explanation for developers, explaining why the error occurred. This field is not intended for end users.
• displayMessage (optional) – A customer-facing message that can safely be shown in the UI. If no displayMessage is provided, display a generic error message instead.

Error Example Response

{
  "errorCode": "NO_REMAINING_BALANCE_TO_VOID",
  "errorMessage": "There is no remaining balance for payment 'J3050040352'",
  "displayMessage": "There was an error voiding payment 'J3050040352'."
}

Error Handling by Workflow

Each payment workflow (e.g., online, in-person, voice) has a specific error handling process. These workflows may vary depending on the integration type and the reconciliation options chosen.

Refer to the relevant integration documentation for detailed error workflow handling steps. Reach out to PaymentExpress if you need more details.

Best Practices

• Always log the errorCode and errorMessage for debugging.
• Show only displayMessage (if provided) to end users. Otherwise, provide a generic error message such as “Something went wrong. Please try again.”