baron-sso/docs/userfront_error_handling_policy.md

UserFront Error Handling Policy

1. 목적

• UserFront의 /error 화면에서 에러 코드 노출 정책을 일관되게 유지합니다.
• Ory에서 전달되는 표준 에러 코드는 별도 bypass 규칙으로 처리합니다.
• 내부 코드와 번역 리소스의 누락을 자동 검증합니다.

2. 처리 원칙

1. 프로덕션에서 에러 분기 기준은 error 문자열이 아니라 code입니다.
2. ORY error code는 bypass 규칙으로 처리합니다.
3. ORY 코드 외 항목은 내부 whitelist를 기준으로 노출합니다.
4. whitelist/bypass에 없는 코드는 unknown_error로 처리합니다.

3. 코드 분류

기준 파일: userfront/lib/core/constants/error_whitelist.dart

3.1 Internal whitelist

• settings_disabled
• invalid_session
• verification_required
• recovery_expired
• recovery_invalid
• rate_limited
• not_found
• bad_request
• password_or_email_mismatch

3.2 ORY bypass

• access_denied
• consent_required
• interaction_required
• invalid_client
• invalid_grant
• invalid_request
• invalid_scope
• login_required
• request_forbidden
• server_error
• temporarily_unavailable
• unauthorized_client
• unsupported_response_type

4. i18n 키 구조

• 내부 whitelist: msg.userfront.error.whitelist.{code}
• ORY bypass: msg.userfront.error.ory.{code}

리소스는 아래 파일 모두에 키가 있어야 합니다.

• locales/template.toml
• locales/ko.toml
• locales/en.toml
• userfront/assets/translations/template.toml
• userfront/assets/translations/ko.toml
• userfront/assets/translations/en.toml

5. 검증

키 누락 검증 스크립트:

./scripts/verify_userfront_error_i18n.sh

화면 동작 테스트:

cd userfront
flutter test test/error_screen_test.dart

6. 관련 이슈

• #164 [UserFront] 에러 노출 whitelist 정의 및 적용
• #259 백엔드 i18n/에러 메시지 fallback 정책 재정리 및 반영 계획 수립
• #260 [Backend] 에러 응답 code 통일 구현 계획 (phase rollout)