docs: cleanup handling exceptions

Signed-off-by: heitorlessa <[email protected]>

Author: heitorlessa

docs/utilities/idempotency.md

@@ -305,41 +305,16 @@ Here is an example on how you register the Lambda context in your handler:
 
 ### Handling exceptions
 
-If you are using the `idempotent` decorator on your Lambda handler, any unhandled exceptions that are raised during the code execution will cause **the record in the persistence layer to be deleted**.
-This means that new invocations will execute your code again despite having the same payload. If you don't want the record to be deleted, you need to catch exceptions within the idempotent function and return a successful response.
+There are two failure modes that can cause new invocations to execute your code again despite having the same payload:
 
-<center>
-```mermaid
-sequenceDiagram
-    participant Client
-    participant Lambda
-    participant Persistence Layer
-    Client->>Lambda: Invoke (event)
-    Lambda->>Persistence Layer: Get or set (id=event.search(payload))
-    activate Persistence Layer
-    Note right of Persistence Layer: Locked during this time. Prevents multiple<br/>Lambda invocations with the same<br/>payload running concurrently.
-    Lambda--xLambda: Call handler (event).<br/>Raises exception
-    Lambda->>Persistence Layer: Delete record (id=event.search(payload))
-    deactivate Persistence Layer
-    Lambda-->>Client: Return error response
-```
-<i>Idempotent sequence exception</i>
-</center>
+* **Unhandled exception**. We catch them to delete the idempotency record to prevent inconsistencies, then propagate them.
+* **Persistent layer errors**. We raise **`IdempotencyPersistenceLayerError`** for any persistence layer errors _e.g., remove idempotency record_.
 
-If you are using `idempotent_function`, any unhandled exceptions that are raised _inside_ the decorated function will cause the record in the persistence layer to be deleted, and allow the function to be executed again if retried.
+If an exception is handled or raised **outside** your decorated function, then idempotency will be maintained.
 
-If an Exception is raised _outside_ the scope of the decorated function and after your function has been called, the persistent record will not be affected. In this case, idempotency will be maintained for your decorated function. Example:
-
-=== "Handling exceptions"
-
-    ```python hl_lines="18-22 28 31"
-    --8<-- "examples/idempotency/src/working_with_exceptions.py"
-    ```
-
-???+ warning
-    **We will raise `IdempotencyPersistenceLayerError`** if any of the calls to the persistence layer fail unexpectedly.
-
-    As this happens outside the scope of your decorated function, you are not able to catch it if you're using the `idempotent` decorator on your Lambda handler.
+```python title="working_with_exceptions.py" hl_lines="21 32 38"
+--8<-- "examples/idempotency/src/working_with_exceptions.py"
+```
 
 ### Persistence layers
 
@@ -635,6 +610,26 @@ sequenceDiagram
 <i>Concurrent identical in-flight requests</i>
 </center>
 
+#### Unhandled exception
+
+<center>
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Lambda
+    participant Persistence Layer
+    Client->>Lambda: Invoke (event)
+    Lambda->>Persistence Layer: Get or set (id=event.search(payload))
+    activate Persistence Layer
+    Note right of Persistence Layer: Locked during this time. Prevents multiple<br/>Lambda invocations with the same<br/>payload running concurrently.
+    Lambda--xLambda: Call handler (event).<br/>Raises exception
+    Lambda->>Persistence Layer: Delete record (id=event.search(payload))
+    deactivate Persistence Layer
+    Lambda-->>Client: Return error response
+```
+<i>Idempotent sequence exception</i>
+</center>
+
 #### Lambda request timeout
 
 <center>

examples/idempotency/src/working_with_exceptions.py

@@ -1,37 +1,38 @@
+import os
+
 import requests
 
 from aws_lambda_powertools.utilities.idempotency import (
     DynamoDBPersistenceLayer,
     IdempotencyConfig,
     idempotent_function,
 )
+from aws_lambda_powertools.utilities.idempotency.exceptions import IdempotencyPersistenceLayerError
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-persistence_layer = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
+table = os.getenv("IDEMPOTENCY_TABLE")
+persistence_layer = DynamoDBPersistenceLayer(table_name=table)
 
 config = IdempotencyConfig()
 
 
-def lambda_handler(event: dict, context: LambdaContext):
-    # If an exception is raised here, no idempotent record will ever get created as the
-    # idempotent function does not get called
-    try:
-        endpoint = "https://jsonplaceholder.typicode.com/comments/"  # change this endpoint to force an exception
-        requests.get(endpoint)
-    except Exception as exc:
-        return str(exc)
-
-    call_external_service(data={"user": "user1", "id": 5})
-
-    # This exception will not cause the idempotent record to be deleted, since it
-    # happens after the decorated function has been successfully called
-    raise Exception
-
-
 @idempotent_function(data_keyword_argument="data", config=config, persistence_store=persistence_layer)
 def call_external_service(data: dict):
+    # Any exception raised will lead to idempotency record to be deleted
     result: requests.Response = requests.post(
         "https://jsonplaceholder.typicode.com/comments/",
-        json={"user": data["user"], "transaction_id": data["id"]},
+        json=data,
     )
     return result.json()
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    try:
+        call_external_service(data=event)
+    except IdempotencyPersistenceLayerError as e:
+        # No idempotency, but you can decide to error differently.
+        raise RuntimeError(f"Oops, can't talk to persistence layer. Permissions? error: {e}")
+
+    # This exception will not impact the idempotency of 'call_external_service'
+    # because it happens in isolation, or outside their scope.
+    raise SyntaxError("Oops, this shouldn't be here.")

includes/abbreviations.md

@@ -1 +1,2 @@
 *[observability provider]: An AWS Lambda Observability Partner
+*[unhandled exception]: An exception that is not caught by any explicit try/except block