--- title: "Orchestration Error Handling with Trusted Device microservice" slug: "oca-ig-orchestration-error-handling-with-trusted-device-microservice" updated: 2025-07-04T10:09:41Z published: 2025-07-08T14:14:51Z canonical: "docs.onespan.com/oca-ig-orchestration-error-handling-with-trusted-device-microservice" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.onespan.com/llms.txt > Use this file to discover all available pages before exploring further. # Orchestration Error Handling with Trusted Device microservice The Trusted Device microservice and its endpoint, [POST /orchestration-commands-v2](https://community.onespan.com/products/onespan-cloud-authentication/sandbox#/Device Commands/trustedDeviceCmdv2UsingPOST), 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: ```json {    "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. |