Fix OAuth error response mapping for authentication endpoints

[nicknisi]

Summary

Fixes #287 - OAuth/authentication endpoints return errors in a different format than standard API errors, causing null exception messages.

Problem

When authenticateWithCode fails with an invalid/expired code, WorkOS returns:

{
  "error": "invalid_grant",
  "error_description": "The code 'X' has expired or is invalid."
}

But the SDK expected:

{
  "message": "...",
  "code": "...",
  "errors": [...]
}

This mismatch caused all exception fields to be null, making debugging difficult.

Solution

• Added OAuthErrorResponse class for OAuth error format
• Updated error handling to detect OAuth vs standard error responses
• Maps OAuth errors to existing BadRequestException to maintain backward compatibility
• No breaking changes - existing error handling continues to work

Test Plan

• Added tests for OAuth error with description
• Added tests for OAuth error without description (optional per spec)
• Verified existing error handling still works
• All tests pass

[greptile-apps]

Greptile Summary

This PR fixes a critical bug in OAuth authentication error handling within the WorkOS Kotlin SDK. The issue was that authentication endpoints return errors in the OAuth 2.0 standard format ({"error": "...", "error_description": "..."}) while the SDK was attempting to parse all 400 errors using the standard WorkOS API error format ({"message": "...", "code": "...", "errors": [...]}). This format mismatch caused authentication failure exceptions to have null messages and codes, making debugging impossible.

The solution introduces a new OAuthErrorResponse data class that properly maps the OAuth error format using Jackson annotations. The error handling logic in WorkOS.kt has been enhanced to detect the error format by examining the JSON structure - if the response contains an "error" field and either has an "error_description" field or lacks a "message" field, it's treated as an OAuth error. The OAuth error data is then mapped to the existing BadRequestException constructor parameters to maintain complete backward compatibility.

Additionally, the PR includes a defensive fix for potential null pointer exceptions by changing the X-Request-ID header retrieval from first() to firstOrNull() with a fallback to "unknown". Comprehensive test coverage has been added to verify both OAuth errors with and without error descriptions, ensuring the fix works correctly while preserving existing functionality.

Confidence score: 4/5

• This PR addresses a real usability issue with proper error format detection and maintains backward compatibility
• The solution correctly implements OAuth 2.0 error response handling while preserving existing exception types
• Pay close attention to the error detection logic in WorkOS.kt to ensure it properly differentiates between error formats

_{3 files reviewed, no comments}

_{Edit Code Review Bot Settings | Greptile}