docs: add error-handling example for BatchResult on Map operations page

[yaythomas]

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 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

[yaythomas]

ditto parallel