aws / aws/aws-durable-execution-docs
docs: add error-handling example for BatchResult on Map operations page
- Dominant language
- Python
- Stars
- 13
- Forks
- 13
- Avg merge
- 3d 2h
- Merged PRs (30d)
- 25
Description
## Problem
When using `context.map()` with `CompletionConfig.all_successful()`, if all map items throw exceptions, `get_results()` returns an empty list with no indication of what went wrong. Users who are not already aware of `BatchResult.get_errors()` and `BatchResult.failed()` tend to fall back to wrapping their map function body in `try/except` and returning a result dict so they can inspect failures — even though the SDK already exposes a proper API for this.
The root cause appears to be discoverability: the error-inspection methods exist and are reference-documented, but nothing on the map operation page nudges users toward them.
## Current docs state
The [Map operations reference](https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/map/#result-types) does document the following on `BatchResult`:
- `get_results()`
- `get_errors()`
- `succeeded()`
- `failed()`
- `throw_if_error()`
However:
- The **introductory example** at the top of the page only shows `result.getResults()` / `result.to_dict()` — the success path.
- There is **no error-handling example** on the map page itself.
- There is no guidance on how to combine `CompletionConfig` with partial success/failure inspection.
As a result, users reading the page top-down can easily walk away thinking the only way to see per-item failures is to catch exceptions inside the map function.
## Suggested improvement
1. **Add an "Error handling" section** on the Map operations page, positioned immediately after the basic example. It should include:
- A short explanation that `BatchResult` exposes both the successful and failed items, and that catching exceptions inside the map function is not required to inspect failures.
- A runnable code sample using `CompletionConfig` (e.g. `all_successful()` and at least one more permissive variant) that demonstrates iterating over `get_errors()` and `failed()` to inspect partial success/failure.
- A note on when `get_results()` returns an empty list vs. raises, so the empty-list case does not surprise users.
2. **Add a "Common patterns" subsection** to the map page covering:
- Inspecting partial failures without raising.
- Re-raising selectively after inspection (via `throw_if_error()` or manual logic).
- Choosing between `CompletionConfig` modes based on the desired failure semantics.
3. **Cross-link** from the introductory example to the new "Error handling" section so users scanning the page see the pointer before they write their own `try/except` workaround.
## Severity
Low — the API exists and works; this is a documentation discoverability gap, not a functional one.
## Affected docs
- [Map operations reference — Result types](https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/map/#result-types)
Contributor guide
Assessment
This issue has not been assessed yet.