Error Handling

Transact surfaces errors at several layers — from client-side field validation through to API response codes and PSP transaction outcomes. This page describes each category and how errors are communicated to agents, integrators and end-customers.

---

API Error Response Structure

All Transact API errors return a consistent ApiErrorResponse body:

{
  "errorId": "a-3f2a1b4c-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
  "httpStatus": 400,
  "statusMessage": "Session not found",
  "errorType": 0,
  "timestamp": "2026-03-20T14:30:00Z",
  "path": "/api/cardcapture/session/cc-abc123"
}

Field	Type	Description
errorId	string	Unique identifier for the error instance. Include this when raising support tickets.
httpStatus	integer	The HTTP status code for the response.
statusMessage	string	Human-readable description of the error.
errorType	integer	Error classification — 0 (Validation), 1 (Authentication), 2 (Authorisation), 3 (System).
timestamp	date-time	UTC timestamp of when the error occurred.
path	string	The API endpoint where the error was raised.

---

Client-Side Validation Errors

Before any API call is made, the Transact UI validates captured card data on the agent or customer form:

Validation	Applies To	Description
Luhn check	PAN	The card number is validated against the Luhn algorithm. Controlled by ValidateLuhn in the configuration.
Card scheme	PAN	PAN length and prefix are checked against allowed card schemes. If allowedCardTypes is provided, only those schemes are accepted.
Expiry date format	Expiry	Must be a valid future date in the expected format.
CSC length	CSC	Must match the expected length for the detected card scheme (3 or 4 digits).
Mandatory fields	All capture fields	Fields configured as required must be completed before the Submit button becomes active.

Validation errors are shown as visual prompts inline on the capture form. The agent cannot submit the form until all validations pass.

---

Authentication & Authorisation Errors

These errors occur during login, token management and role-based access control.

Authentication (401)

Endpoint	Description
Login	Credentials are invalid, account is locked out, or password has expired.
Passwordless Login	Credentials are invalid or the account is locked out.
Service Token	The service token is missing, invalid, or inactive.
Refresh Token	The token is missing, expired, or invalid.
All other endpoints	The bearer token is missing, expired, or invalid.

Common causes: Expired JWT, missing Authorization header, revoked refresh token, locked user account.

Authorisation (403)

Endpoint	Description
Login / Passwordless Login	Caller does not have the required role.
Refresh Token	The refresh token has been revoked.
Reset Password	The password reset token has expired.
Card Data Retrieval	Caller does not have the cardDataRetrieval role.
All other endpoints	Caller does not have the required role for the operation.

User Not Found (404)

Endpoint	Description
Login / Passwordless Login	The specified user was not found.
App Token from Service Token	The account or service token was not found.
Reset Password	The user was not found or is inactive.

---

Correlation Errors

Call correlation links the agent's web session with the customer's phone call. Errors here prevent the capture phase from starting.

Code	Endpoint	Description
400	Associate Account	Required fields are missing from the request body.
400	Find Call / Search Calls	accountShortGuid not present in the bearer token.
400	Manual Correlation	Required claims or fields are missing.
404	Associate Account	The call was not found in the active call pool.
404	Find Call	No call matching the specified criteria was found.
404	Search Calls	No calls matching the specified criteria were found.
404	Manual Correlation	The manual correlation session was not found.

Common causes: Call has ended before correlation completed, incorrect dialogId or sipCallId, caller number mismatch, account parameter incorrect.

---

Card Capture Errors

Errors during the card capture session lifecycle — creating, capturing, retrieving or deleting card data.

Session Management

Code	Endpoint	Description
400	Create Session	Failed to create the session.
400	Delete Session	Failed to delete the session.
404	Create Session	No matching call found for the provided DialogId or SipCallId.
404	Get / Delete Session	No session exists for the given key.

Capture Initiation

Code	Endpoint	Description
400	Initiate PAN Capture	Invalid request — bad method, duplicate keys, or invalid DTMF control values.
400	Initiate CSC Capture	Invalid request — bad method, duplicate keys, or invalid DTMF control values.
400	Initiate Expiry Date Capture	Invalid request — bad method, duplicate keys, or invalid DTMF control values.
404	All initiate endpoints	Session not found for the given key.

Data Operations

Code	Endpoint	Description
400	Set PAN / CSC / Expiry Value	Failed to set the value.
400	Update PAN / CSC / Expiry Status	Invalid capture status value.
400	Delete PAN / CSC / Expiry	Failed to delete the data.
400	Get Card Data	Invalid request or error retrieving card data.
403	Get Card Data	Caller does not have the cardDataRetrieval role.
404	All data endpoints	Session or data not found for the given key.

---

PSP & Transaction Completion Errors

After card data is captured and submitted, the outcome depends on the PSP response and the configured completion method.

Completion Methods

Transact supports three completion actions, configured per journey. Multiple can be active simultaneously:

Method	Description
Completion Form	Displays a result screen to the agent with configurable success, error and cancel views. Each view shows fields (key/value pairs populated from session data) and text (title, message, note).
Redirect	Navigates the browser to a configured URL. Separate URLs can be configured for each outcome: redirectOnSuccessUrl, redirectOnCancelUrl, redirectOnErrorUrl. Supports GET or POST verb.
Datapost	Sends transaction data via HTTP to a configured endpoint. Separate URLs for each outcome: datapostOnSuccessUrl, datapostOnCancelUrl, datapostOnErrorUrl. Supports browser-origin (fromBrowser) or server-origin (fromServer) with form-urlencoded or json content types.

Client-Initiated PSP Transactions

When the calling application initiates the PSP transaction (using captured card data retrieved via the API):

• Validation errors — Agents see visual prompts for data or formatting errors inline on the capture form.
• Service errors — Subphonic service errors appear via in-app notifications.
• PSP errors — Are proxied back to the calling service in the API response. The calling application is responsible for handling and displaying the PSP outcome.

Subphonic-Initiated PSP Transactions

When Transact itself initiates the PSP transaction on form submission:

• Validation errors — Same inline visual prompts as above.
• Service errors — Subphonic service errors appear via in-app notifications.
• PSP errors — The PSP response is routed through the configured completion method(s):
  • Completion form — The error view is shown with the PSP response mapped into the configured fields.
  • Redirect — The browser navigates to redirectOnErrorUrl with the configured error fields.
  • Datapost — Transaction data including the error is posted to datapostOnErrorUrl.

PSP Outcome Routing

PSP Outcome	Completion Form View	Redirect URL Parameter	Datapost URL Parameter
Success	completionForm.success	redirectOnSuccessUrl	datapostOnSuccessUrl
Error	completionForm.error	redirectOnErrorUrl	datapostOnErrorUrl
Cancel	completionForm.cancel	redirectOnCancelUrl	datapostOnCancelUrl

If outcome-specific URLs are not configured, Transact falls back to the generic redirectUrl or datapostUrl parameter.

---

Server Errors (500)

All API endpoints may return a 500 Internal Server Error when an unexpected server error occurs. The response body follows the standard ApiErrorResponse structure.

When receiving a 500 error:

1. Note the errorId from the response.
2. Retry the operation after a brief pause — transient errors may resolve.
3. If the error persists, contact Subphonic Support with the errorId and timestamp.

---

HTTP Status Code Summary

Code	Meaning	Typical Cause
200	Success	Request completed successfully.
201	Created	Resource created (password reset accepted/completed).
400	Bad Request	Missing required fields, invalid values, or failed validation.
401	Unauthorised	Token missing, expired, or invalid.
403	Forbidden	Insufficient role or revoked token.
404	Not Found	Resource does not exist — user, session, call, or card data.
500	Internal Server Error	Unexpected server-side failure.

---