refactor(event_handler): allow to pass dict as argument to exception classes

[shrivarshapoojari]

Issue number: closes #7279

Summary

This PR enhances event handler exception classes to accept both string and dictionary messages, providing developers with the flexibility to pass structured error information while maintaining full backward compatibility. All exception classes in aws_lambda_powertools/event_handler/exceptions.py now support str | dict type annotations and include comprehensive docstrings.

Changes

1. Update Parameter types

• Updated parameter types: Changed from msg: str to msg: str | dict across all exception classes in aws_lambda_powertools/event_handler/exceptions.py

2. Documentation Improvements

• Added comprehensive docstrings to all exception class constructors
• Updated parameter documentation to clearly specify that msg can be either a string or dictionary

3. Affected Exception Classes

• ServiceError
• BadRequestError
• UnauthorizedError
• ForbiddenError
• NotFoundError
• RequestTimeoutError
• RequestEntityTooLargeError
• InternalServerError
• ServiceUnavailableError

User experience

Before Changes

Users were limited to simple string error messages:

# Only string messages supported
raise BadRequestError("Invalid email format")
raise UnauthorizedError("Access denied")
raise NotFoundError("User not found")

After Changes

Users can now choose between simple strings or rich structured error objects:
Option 1: String messages (backward compatible)

raise BadRequestError("Invalid email format")

Option 2: Structured dictionary messages (new capability)

raise BadRequestError({
    "error_code": "VALIDATION_FAILED",
    "message": "Invalid email format",
    "field": "email",
    "provided_value": "invalid-email",
    "expected_format": "[email protected]"
})

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[boring-cyborg]

Thanks a lot for your first contribution! Please check out our contributing guidelines and don't hesitate to ask whatever you need.
In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.33%. Comparing base (4fcf71f) to head (18e9d98).
⚠️ Report is 4 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #7341      +/-   ##
===========================================
- Coverage    96.36%   96.33%   -0.04%     
===========================================
  Files          275      275              
  Lines        13002    13003       +1     
  Branches       966      966              
===========================================
- Hits         12529    12526       -3     
- Misses         366      368       +2     
- Partials       107      109       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[leandrodamascena]

Thanks for working on this @shrivarshapoojari! APPROVED.

[leandrodamascena]

Codecov is reporting indirect changes that are not part of this PR! It's safe to merge.

[boring-cyborg]

Awesome work, congrats on your first merged pull request and thank you for helping improve everyone's experience!