Error Management APIs

Last updated on Apr 10, 2026 at 10:35 PM

Within the Common APIs, the Error Management section provides standardized access to application-level error information generated by ImPAI.

These APIs allow clients to retrieve structured information about known error types, including their identifiers, descriptions, and related metadata. This supports consistent interpretation of error responses across schemes and functional areas.

The Error Management APIs are read-only and are intended for lookup, troubleshooting, and integration support purposes.

1️⃣ List Errors

The Error List API is to be used to retrieve detailed information about specific errors, or request a list of existing errors.

Request Structure

❶ Query Parameters

The following request parameters can be used to filter for specific errors:

Field	Type	Required	Description	Constraints
`category`	String	No	Filter errors by their category.	1-20 chars Enum: `errauthentication`, `errauthorization`, `errconfiguration`, `errdatabase`, `errfliesystem`, `errjsonencode`, `errjssondecode`, `errmsgstore`, `errnetwork`, `errnotimplemented`, `errpanic`, `errparams`, `errrepository`, `errtimeout`, `errtypeconversation`, `errunknown`, `errxmlencode`, and `errxmldecode`
`currentPage`	String	No	Page number to retrieve for paginated results.	Decimal char >= 1
`entity`	String	No	Filter errors by the related entity.	1-20 chars
`message`	String	No	Filter errors by a specific error message or message content.	–
`objectReference`	String	No	Filter errors by the reference of the object related to the error.	1-20 chars
`objectReferenceType`	String	No	Filter errors by the type of the object reference.	1-36 chars
`objectType`	String	No	Filter errors by the type of object involved (e.g., directory, file).	1-36 chars Enum: `directory` `file` `service` `transaction`
`pageSize`	String	No	Maximum number of records to return per page.	Decimal chars >= 1, <= 100, defaults 15
`service`	String	No	Filter errors by the name of the service where the error occurred.	1-36 chars
`severity`	String	No	Filter errors by severity level (e.g., fatal, high).	1-6 chars Enum: `fatal` `high` `low` `medium`
`status`	String	No	Filter errors by their current status (e.g., New, Resolved).	1-30 chars
`timestampFrom`	String	No	Start of the date/time range to filter errors.	Format: YYYY-MM-DDTHH:MM or YYYY-MM-DDTHH:MM/timezone
`timestampTo`	String	No	End of the date/time range to filter errors.	Format: YYYY-MM-DDTHH:MM or YYYY-MM-DDTHH:MM/timezone

Response Structure

🟢 Success — HTTP 200

HTTP 200 – OK responses for successfully processed messages include:

Group	Description
`header`	A group containing `responseId`, `originalRequestId`, `responseTime`
`metaData`	An object containing meta information about pagination and the actual request represented by `pagination.currentPage`, `pagination.pageSize`, `pagination.totalPages`, `pagination.totalRecords`, `sort.sortBy`, `sort.sortOrder`, `filters`, `message`, and `timeStamp`
`results`	An array of objects, each one containing detail information about 1 account: `category`, `entity`, `id`, `internalCode`, `internalId`, `isoCode`, `message`, `objectReference`, `objectReferenceType`, `objectType`, `service`, `severity`, `status`, `timestamp`, and `type`

Example(s)

{
  "header": {
    "responseId": "0a816627-7899-49e4-ae47-c118d5e3cf50",
    "origRequestId": "ReqId-419578",
    "responseTime": "2025-04-14T07:30:00Z"
  },
  "metaData": {
    "pagination": {
      "currentPage": 1,
      "pageSize": 10,
      "totalPages": 1,
      "totalRecords": 2
    },
    "sort": {
      "orderBy": [
        "CRTDAT"
      ],
      "sortOrder": [
        " desc"
      ]
    },
    "filters": { },
    "message": "Successfully retrieved 2 transactions"
  },
  "results": [
    {
      "category": "errauthentication",
      "entity": "PaymentService",
      "id": "a6172436-4431-4dac-bad0-a943396ccb75",
      "internalCode": "00T00015",
      "internalId": "1d6f5c3a-02e6-4080-995a-8a81327830f6",
      "isoCode": "EUR",
      "message": "Transaction could not completed successfully.",
      "objectReference": "PAI1500003534333",
      "objectReferenceType": "GlobalId",
      "objectType": "directory",
      "service": "common_proc",
      "severity": "fatal",
      "status": "New",
      "timestamp": "2025-06-12T15:04:05Z",
      "type": "Technical"
    }
  ]
}

🔴 Error — HTTP 400

Responses for HTTP 400 – Bad Request errors are returned if validation or logical checks fail and include:

Group	Description
`header`	Response metadata containing `responseId`, `originalRequestId`, `responseTime`
`error`	An object with a human-readable description in `message`

Example(s)

{
  "header": {
    "originalRequestId": "ReqId-419578",
    "responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
    "responseTime": "2025-04-14T07:30:00Z"
  },
  "error": {
    "message": "Invalid query parameters provided"
  }
}

🟡 Error — HTTP 500

Responses for HTTP 500 — Server Error errors are returned on unexpected server-side failures and contain:

Group	Description
`errorCode`	Application-level error identifier (e.g. `500_INTERNAL_ERROR`)
`message`	Brief description such as "Time-out" or "Something went wrong"

Example(s)

{
  "errorCode": "500_INTERNAL_ERROR",
  "message": "Something went wrong"
}

⬇ Try this endpoint in the Live API Explorer

GET/api/common/v1/get-errorsList available Errors

2️⃣ Error Details

The Error Details API is to be used to retrieve detailed information about a single specific error.

Request Structure

❶ Query Parameters

The following request parameter must be used to request an error's details:

Field	Type	Required	Description	Constraints
`id`	UUID	No	Unique identifier of the error.	–

Response Structure

🟢 Success — HTTP 200

HTTP 200 – OK responses for successfully processed messages include:

Group	Description
`header`	A group containing `responseId`, `originalRequestId`, `responseTime`
`results`	An array of objects, each one containing detail information about 1 account: `category`, `entity`, `id`, `internalCode`, `internalId`, `isoCode`, `message`, `objectReference`, `objectReferenceType`, `objectType`, `service`, `severity`, `status`, `timestamp`, and `type`

Example(s)

{
  "header": {
    "responseId": "0a816627-7899-49e4-ae47-c118d5e3cf50",
    "origRequestId": "ReqId-419578",
    "responseTime": "2025-04-14T07:30:00Z"
  },
  "results": [
    {
      "category": "errauthentication",
      "entity": "PaymentService",
      "id": "a6172436-4431-4dac-bad0-a943396ccb75",
      "internalCode": "00T00015",
      "internalId": "1d6f5c3a-02e6-4080-995a-8a81327830f6",
      "isoCode": "EUR",
      "message": "Transaction could not completed successfully.",
      "objectReference": "PAI1500003534333",
      "objectReferenceType": "GlobalId",
      "objectType": "directory",
      "service": "common_proc",
      "severity": "fatal",
      "status": "New",
      "timestamp": "2025-06-12T15:04:05Z",
      "type": "Technical"
    }
  ]
}

🔴 Error — HTTP 400

Responses for HTTP 400 – Bad Request errors are returned if validation or logical checks fail and include:

Group	Description
`header`	Response metadata containing `responseId`, `originalRequestId`, `responseTime`
`error`	An object with a human-readable description in `message`

Example(s)

{
  "header": {
    "originalRequestId": "ReqId-419578",
    "responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
    "responseTime": "2025-04-14T07:30:00Z"
  },
  "error": {
    "message": "Invalid query parameters provided"
  }
}

🟡 Error — HTTP 500

Responses for HTTP 500 — Server Error errors are returned on unexpected server-side failures and contain:

Group	Description
`errorCode`	Application-level error identifier (e.g. `500_INTERNAL_ERROR`)
`message`	Brief description such as "Time-out" or "Something went wrong"

Example(s)

{
  "errorCode": "500_INTERNAL_ERROR",
  "message": "Something went wrong"
}

⬇ Try this endpoint in the Live API Explorer

GET/api/common/v1/get-error-detailGet Error Details

Summary — Error Management

The Error Management section exposes two complementary endpoints:

Error List API — Retrieve a list of recorded errors and optionally filter for specific error cases.
Error Details API — Retrieve the full details for one specific error entry.

Together, these APIs provide:

A centralized way to discover and query recorded errors in ImPAI,
Detailed error context for troubleshooting and operational support (e.g., message reference, timestamps, technical reason text/codes where available),
A consistent basis for monitoring and investigating failed or rejected processing steps.

The functionality is purely informational and does not modify error states or transaction data.

1️⃣ List Errors​

2️⃣ Error Details​

Summary — Error Management​

1️⃣ List Errors

2️⃣ Error Details

Summary — Error Management