Orchestration error handling with the Trusted Device microservice

The Trusted Device microservice and its endpoint, POST /orchestration-commands-v2, provide a range of error responses in connection with orchestration.

To process these error messages, you need to integrate OneSpan Cloud Authentication with the Orchestration SDK with version 4.24.0 and later!

Payloads

The HTTP error response JSON payload required for error handling with the Trusted Device microservice looks like this:

{
    "title": "TrustedDeviceErrorOutputDto",
    "type": "object",
    "properties": {
        "errorCategory": {
            "description": "Category of the error message",
            "type": "string",
            "enum": ["system", "user", "provisioning", "authenticator", "session", "risk", "authentication", "transaction"]
        },
        "errorCode": {
            "description": "Numerical value uniquely identifying the error",
            "type": "integer"
        },
        "message": {
            "description": "Generic human readable error description",
            "type": "string"
        },
        "command": {
            "description": "Hexadecimal string representing the TLV encoded ErrorResponseOC orchestration command",
            "type": "string"
        },
        "service": {
            "description": "Name of the TID microservice handling the request",
            "type": "string"
        },
        "logCorrelationId": {
            "description": "Correlation ID for logging purposes",
            "type": "string"
        },
        "timestamp": {
            "description": "Server-side timestamp of the error",
            "type": "string"
        },
        "validationErrors": {
            "description": "List of objects describing input JSON validation errors",
            "type": "array"
        }
    },
    "required": [
        "errorCategory",
        "errorCode",
        "message",
        "command",
        "service",
        "logCorrelationId",
        "timestamp"
    ]
}

The error response orchestration command payload includes the following fields:

Orchestration command payload fields
Field Type Description
returnCode int Numerical value uniquely identifying the error.
readableMessage String Generic human readable error description.
customPayload String Optional. Specific human readable error description or additional data.
errorType ErrorType enum UNKNOWN for unexpected errors, GENERIC for expected errors.
flowType String The current orchestration flow derived from the previousCommandType field.
previousCommandType OrchestrationCommandType enum Type of orchestration command that triggered the error.
commandSessioId String ID of the failed orchestration session.
Orchestration server error client callback payload fields
Field Type Description
readableMessage String Generic human readable error description
customPayload String Optional. Specific human readable error description or additional data.