Lambda Error Handling

Goal

Build a robust error-handling layer for your SEC Lambda functions so that failures surface clearly in logs, callers receive structured error responses, and you can diagnose problems without redeploying.

Contract

Your Lambda function must:

Return a structured JSON error response (not a stack trace) when something goes wrong.
Distinguish between client errors (bad input) and server errors (downstream failures).
Produce CloudWatch log entries that let you trace a specific invocation from request to failure.
Set the appropriate HTTP status code when invoked behind API Gateway (via the Lambda contract).

When another Lambda invokes yours synchronously, the caller must detect failures via the FunctionError field in the invoke response — not by parsing the payload alone.

Required Reading

Constraints

Use try/except (Python's term — not "try/catch").
Every except block must log the exception with enough context to identify the failing invocation (request ID, input parameters).
Never return a raw traceback to callers. Return a JSON body with an error key describing the failure class.
When invoking another Lambda with boto3, always check the response for the FunctionError key before reading the payload.
Use sam logs and sam local invoke for local reproduction before deploying diagnostic changes.
All model references link to the Models reference page.

Acceptance Criteria

Your handler wraps all business logic in a try/except that catches specific exception types before a final catch-all Exception.
A Bedrock invoke_model call that fails (throttle, invalid input, expired model) is caught, logged with the request context, and returned as a structured error.
An SEC EDGAR HTTP request that fails (network timeout, 403 from missing User-Agent, non-200 status) is caught and surfaced with the URL that failed.
When Lambda A invokes Lambda B synchronously, Lambda A checks response["FunctionError"] and handles the downstream failure without crashing.
You can find your Lambda's log group in CloudWatch, locate a specific invocation by request ID, and read the error output.
You can reproduce a failure locally using sam local invoke with a test event, and stream deployed logs using sam logs --tail.

Hints

Structuring the try/except

Catch the narrowest exceptions first. For Bedrock calls, botocore.exceptions.ClientError covers API-level failures. For HTTP calls, requests.exceptions.RequestException covers network-level failures. A final except Exception prevents unhandled crashes but should log at ERROR level — it means you missed a case.

Detecting FunctionError from a caller

When you call lambda_client.invoke(FunctionName=..., Payload=...), the response dict always has a StatusCode. But a 200 status does NOT mean the invoked function succeeded — Lambda returns 200 for the transport even when the function itself raised an error. Check response.get("FunctionError"). If present, the value is "Handled" or "Unhandled" and the Payload contains the error output, not your expected result.

Finding your log group in CloudWatch

Lambda log groups follow the naming pattern /aws/lambda/<function-name>. Inside the log group, each invocation creates log entries prefixed with the request ID. Search for that ID to isolate a single execution. The START, END, and REPORT lines bracket each invocation and show duration, memory used, and billed duration.

Using sam logs and sam local invoke

sam logs -n YourFunctionName --stack-name your-stack --tail streams live logs from the deployed function — useful during integration testing. sam local invoke YourFunctionName -e events/test-event.json runs the function in a local Docker container using your template.yaml definition — useful for reproducing errors without deploying.

Consolidated error list

Your SEC Lambda functions will encounter these error categories: