Camunda 8 Rest connector error handling and retry policy

[PD12345]

Hi,
I’m trying to develop error handling for REST connector and during tests of my solution I noticed one weird thing and i cannot find answer why it happens.
On the REST connector in error handling section I have this expression:

if error != null 
then 
  bpmnError("CHECK_ERROR", "CHECK_ERROR", {checkError: error}) 
else 
  null

And in retries section I have set retries value to 3 and retry backoff as PT0S.
During tests I have noticed that if error occurs in first API call, then activity with REST call is ended and boundary error event path continues the process. There is no 3 retries, like it was set in retries section.
Is it possible to configure error handling to do 3 retries before error is thrown? Or I have to do it by wrapping this REST connector activity by gateways and variables used for retry count?

[sbuettner]

Hey @PD12345, you might want to use the jobError() function documented here.

[aravindhrs]

Hi @PD12345 ,

Why Your REST Connector Skips Retries on Error

In Camunda 8, when you’re using error handling expressions (like bpmnError(...)), you’re telling the connector to handle the error gracefully and pass control to the process, rather than fail the job.

Here’s what’s happening in your case:

• The REST connector executes and encounters an error.
• Your error != null ? bpmnError(...) : null expression triggers a BPMN error.
• Throwing a BPMN error is considered a business-level exception, not a technical failure.
• Therefore, no retries are executed — the connector assumes the error was “handled” via the boundary event and continues.

Retry policies are only triggered when the job actually fails, i.e., when an unhandled exception occurs and no BPMN error is thrown.

---

If You Want Retries First, THEN Error Event

You have two main options:

Option 1: Let the REST connector fail technically first

1. Don’t use bpmnError(...) immediately in the connector error handling.
2. Let the REST connector throw an error (like a 500 response), and don’t catch it via bpmnError.
3. Set retries = 3 and retryBackoff = PT0S to retry immediately.

Then, after 3 failed retries, the job will fail and you can:

• Catch the job error using a boundary error event on the service task, or
• Use a Catch-all Error Start Event on a subprocess or error handler flow.

Example:

error: null

This way, Camunda retries the REST call first.

---

Option 2: Implement custom retry logic within the process

If you need full control (e.g., retry only on certain error codes, delay between retries, etc.), you can do this manually:

• Add a looping subprocess around the connector call.
• Track retry attempts in a variable (e.g., retryCount).
• If the connector fails, use an Exclusive Gateway to decide:
  • Retry (if retryCount < 3)
  • Exit via error path (if max retries hit)

This is more flexible but requires BPMN modeling work.

---

Suggested Minimal Change (Hybrid Option)

If you want to keep using the error expression, but still leverage retries:

• Only throw a BPMN error after all retries fail.
• In the error handling expression, add logic to count the number of errors, and only throw bpmnError if you’re on the final retry.

But unfortunately, connectors don’t expose the retry attempt number to the expression directly, so this gets complex fast.

Hence:

Best practice = Let the connector job fail naturally first, use retry policies, and only use BPMN errors when you really want to skip retries.