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. Backend code 주입/매핑 경로

• 기본 매핑 함수: backend/internal/response/error_response.go
  • 404 -> not_found
  • 429 -> rate_limited
• legacy 응답 보강 미들웨어: backend/internal/middleware/error_code_enricher.go
  • 핸들러가 {"error": ...}만 반환해도 status 기반 code를 주입
• 신규 권장 패턴: response.Error(...) 또는 공통 helper(errorJSON, errorJSONCode)로 핸들러에서 명시 코드 반환

UserFront는 위 경로로 전달된 code를 기준으로 whitelist/ory/unknown 분기를 수행합니다.

7. 관련 이슈

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