User Story (Required on creation):

High level

• As a developer, I want to be able to handle exceptions that can be retried in my client. To do so in a differentiated way (e.g.: customized retry logic within the external task client) I do need detailed exception error codes.
• As a developer, I want to simplify my retry mechanism that currently evaluates exception messages.

Low level

As a developer (user), I can:

• access codes on Java, REST, and Open API level
• use predefined built-in error codes (listed in functional requirements)
• lookup codes in our documentation and understand if they are safely retryable
• add new codes myself via an extension point

Functional Requirements (Required before implementation):

• The Java, REST, and Open APIs return a code property when an exception is thrown by the engine
• The following built-in error situations are detected and codes are assigned:
  • Optimistic Locking / Crdb Transaction Retry (safe to retry)
  • Deadlock (safe to retry)
  • Foreign key constraint violation
  • Column size too small
• A custom code provider can be registered to assign a code to an exception in case the error situation isn't covered built-in so far by the engine
• There is a glossary in the documentation to look up the meaning of the respective code and to understand whether the API call is safe to be retried or not

Technical Requirements (Required before implementation):

• The returned code is numeric
• When no built-in or custom code is provided, the fallback code 0 is returned
• Code ranges
  • Reserved range <= 19,999 and >= 40,000
    • Fallback: 0
    • Engine: [1, 9999]
    • Persistence: [10000, 19999]
    • There is still a lot of unassigned space to build on top in the future
  • Custom code range [20000, 39999]
    • Could potentially be extended if we receive user feedback
• Configuration
  • disableExceptionCode: The whole feature can be disabled entirely
    • To mitigate the impact of regressions, this is realized using a command interceptor that is not part of the chain in case the feature is disabled
  • disableBuiltinExceptionCodeProvider: The built-in code provider can be disabled
    • Like that, users can opt for having full control on codes (no reserved range) using a custom code provider in case they don't want to use our built-in codes
  • customExceptionCodeProvider: A custom code provider can be registered
    • Custom code that violates the reserved range is reset to fallback code 0 and a warning log is written
    • A custom code can only override codes in the reserved range in case the built-in code provider is disabled
• Delegation code
  • A custom code can be assigned to a process engine exception that is thrown from delegation code using the setter method or the constructor
    • A process engine exception can be extended to use a custom exception type
  • Delegation code assignment has precedence over a custom code provider
  • A built-in code provider has precedence over delegation code assignment
    • Currently, no process engine exceptions representing built-in errors can be caught in the delegation code since SQL statements triggered by engine API are collected and executed when the process transaction ends
    • However, let's define this behavior now already to avoid falling into this trap when introducing built-in codes that are unrelated to SQL exceptions
    • If the attempt is made to override a built-in code, a warning is logged.
• Extensibility
  • Custom code provider
    • Can be registered via engine configuration
    • For usability/convenience reasons, the provider has two methods: one is called in case a persistence exception occurred, and the other method is called for all other situations
    • When returning null, the fallback code is assigned
  • The codes <= 19,999 and >= 40,000 are reserved for built-in codes and can only be overridden in case the built-in code provider is disabled
• Open API definition exists
• REST API
  • When the error is not caused by a process engine exception, null is returned
• Documentation
  • disableExceptionCode, disableBuiltinExceptionCodeProvider, customExceptionCodeProvider properties are documented in the engine configuration reference
  • REST API documentation exists
  • User guide covers:
    • how to assign a custom error code in the delegation code
    • built-in vs. custom codes
    • more behavioral details about configuration properties
      • Hint: builtinExceptionCodeProvider engine config property should not be documented; however, it might make sense to be able to configure it either for future development or in case of bugs/regressions
    • how to register custom code provider
    • glossary about built-in codes, whether the respective errors are safe to retry, and ranges
    • reserved code range

Limitations of Scope (Optional):

In this implementation increment (MVP), we only provide built-in codes requested by users.

Hints (optional):

-