fix(OUT-3575): handle Intuit OAuth's new error format for auth errors

[SandipBajracharya]

Summary

• Intuit silently changed their OAuth error response from Axios-style { response: { status, data } } to { error, error_description, intuit_tid }. This caused refresh token expiry errors to go undetected, preventing notification emails to IUs.
• Added IntuitOAuthError extends Error class with a fromRaw() factory method to wrap Intuit's plain-object errors into proper Error instances. This is necessary because pRetry discards non-Error throws.
• Added isIntuitOAuthError type guard (now instanceof based) and updated all error handling paths.
• Extracted OAuthErrorCodes.INVALID_GRANT constant to replace magic string comparisons.

Changes

File	Change
src/app/api/core/exceptions/custom.ts	IntuitOAuthError class with fromRaw() factory + isIntuitOAuthError instanceof guard
src/app/api/core/utils/withErrorHandler.ts	Handle IntuitOAuthError before generic Error branch + Sentry capture
src/app/api/quickbooks/auth/auth.service.ts	Switch from isAxiosError to isIntuitOAuthError, use constant for invalid_grant check
src/constant/intuitErrorCode.ts	Added OAuthErrorCodes with as const
src/utils/error.ts	Handle IntuitOAuthError before generic Error in getMessageAndCodeFromError
src/utils/intuit.ts	Wrap plain Intuit OAuth errors via IntuitOAuthError.fromRaw() in all SDK calls (_refreshAccessToken, _authorizeUri, _createToken)

Key design decisions

• Why IntuitOAuthError extends Error? — pRetry discards non-Error throws with a generic TypeError, losing all Intuit error fields. Wrapping in a proper Error subclass preserves them through the retry pipeline.
• Why fromRaw() factory? — Keeps plain-object shape detection in one place. Callers just do throw IntuitOAuthError.fromRaw(error) ?? error.
• Why reorder isIntuitOAuthError before instanceof Error? — Since IntuitOAuthError extends Error, the generic instanceof Error branch would catch it first, making our specific handler dead code.
• No retry for OAuth errors — shouldRetry in withRetry.ts only retries status === 429. IntuitOAuthError has no status, so it fails fast. Network/rate-limit errors still retry normally.

Test plan

• Simulate expired refresh token — verify turnOffSync is called and IU notification email is sent
• Simulate non-invalid_grant OAuth error (e.g. invalid_client) — verify error is caught and reported to Sentry
• Verify existing Axios-style errors from QuickBooks Data Services API are still handled correctly
• Verify network errors during token refresh are still retried (up to 3 times)

🤖 Generated with Claude Code

[linear]

OUT-3575 Intuit OAuth changed silently changed auth error format

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
quickbooks-sync	Building		Apr 10, 2026 8:42am
quickbooks-sync (dev)	Ready	Preview, Comment	Apr 10, 2026 8:42am

[priosshrsth]

@SandipBajracharya Could you simplify the function to check intuit error?

[priosshrsth]

lgtm