Add email_verification_id field to BaseRequestException

[devin-ai-integration]

Description

Fixes workos#309

Introduces a new EmailVerificationRequiredException that extends AuthorizationException to provide direct access to the email_verification_id field when authentication fails due to unverified email.

Changes

New Exception Class (workos/exceptions.py):

• Added EmailVerificationRequiredException as a subclass of AuthorizationException
• Extracts email_verification_id from the error response JSON
• Includes docstring explaining the exception's purpose

HTTP Client Logic (workos/utils/_base_http_client.py):

• Updated _maybe_raise_error_by_status_code to detect the specific error code
• When status 403 + code: "email_verification_required", raises the new specific exception
• Otherwise raises generic AuthorizationException (preserves existing behavior)

Tests (tests/test_sync_http_client.py):

• Added test verifying EmailVerificationRequiredException is raised with correct fields
• Added test confirming regular AuthorizationException still works for other 403 errors
• Verified the new exception is an instance of AuthorizationException (maintains backward compatibility)

Key Design Decisions

1. Inheritance: EmailVerificationRequiredException extends AuthorizationException rather than adding fields to the base class, providing better type safety and semantic clarity
2. Backward compatibility: Existing code catching AuthorizationException will continue to work
3. Detection mechanism: Uses the code field from the API response to identify this specific error condition

Review Checklist

• Verify "email_verification_required" is the correct/only error code for this scenario
• Confirm there are no other similar error codes that should get specific exception types
• Check if this pattern should be applied to other authentication error scenarios
• Validate the exception hierarchy makes sense for the SDK's design

Before/After

Before:

try:
    workos_client.user_management.authenticate_with_password(...)
except AuthorizationException as exc:
    # Had to manually parse response
    data = json.loads(exc.response.text)
    email_verification_id = data["email_verification_id"]

After:

try:
    workos_client.user_management.authenticate_with_password(...)
except EmailVerificationRequiredException as exc:
    # Direct field access
    email_verification_id = exc.email_verification_id

All 370 tests pass.

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[ ] Yes - This introduces a new exception type that should be documented

If yes, documentation should cover:

• When EmailVerificationRequiredException is raised
• How to access the email_verification_id field
• Example of using the ID to retrieve the verification object or resend email

---

Link to Devin run: https://app.devin.ai/sessions/ec6b5bc71374406895201f8407f1f73c
Requested by: Deep Singhvi (@dsinghvi)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring