Handle External Task Failure

Reports a failure to execute an external task by id. A number of retries and a timeout until the task can be retried can be specified. If retries are set to 0, an incident for this task is created.

Method

POST /external-task/{id}/failure

Parameters

Path Parameters

Name Description
id The id of the external task to report a failure for.

Request Body

A JSON object with the following properties:

Name Description
workerId The id of the worker that reports the failure. Must match the id of the worker who has most recently locked the task.
errorMessage An message indicating the reason of the failure.
errorDetails A detailed error description.
retries A number of how often the task should be retried. Must be >= 0. If this is 0, an incident is created and the task cannot be fetched anymore unless the retries are increased again. The incident's message is set to the errorMessage parameter.
retryTimeout A timeout in milliseconds before the external task becomes available again for fetching. Must be >= 0.

Result

This method returns no content.

Response Codes

Code Media type Description
204 Request successful.
400 application/json Returned if the task's most recent lock was not acquired by the provided worker. See the Introduction for the error response format.
404 application/json Returned if the task does not exist. This could indicate a wrong task id as well as a cancelled task, e.g., due to a caught BPMN boundary event. See the Introduction for the error response format.
500 application/json Returned if the corresponding process instance could not be resumed successfully. See the Introduction for the error response format.

Example

Request

POST /external-task/anId/failure

Request Body:

    {
      "workerId": "aWorker",
      "errorMessage": "Does not compute",
      "retries": 3,
      "retryTimeout": 60000
    }

Response

Status 204. No content.

On this Page: