From e3925415f3a7e31cf594f0996749e2bab06ebfad Mon Sep 17 00:00:00 2001
From: hyoseok <alexization@gmail.com>
Date: Wed, 25 Mar 2026 10:02:45 +0900
Subject: [PATCH 1/2] =?UTF-8?q?refactor:=20=ED=94=84=EB=9F=B0=ED=8A=B8=20A?=
 =?UTF-8?q?PI=20=EA=B3=84=EC=95=BD=20=ED=83=80=EC=9E=85=20=EB=8B=A8?=
 =?UTF-8?q?=EC=9D=BC=ED=99=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- API 응답 계약 기준을 src/shared/types/api.ts로 통합
- validations.ts의 API 응답 중복 선언 제거
- ranking user auth 소비자를 backend OpenAPI 기준에 맞춤
---
 src/app/auth/callback/page.tsx               |  3 +-
 src/app/oauth2/redirect/page.tsx             |  3 +-
 src/app/ranking/page.tsx                     | 12 ++--
 src/app/sitemap.ts                           | 59 ++++++++------------
 src/app/users/[username]/opengraph-image.tsx | 29 ++++------
 src/shared/constants/tier-styles.ts          |  7 +--
 src/shared/lib/api-client.ts                 | 13 +----
 src/shared/lib/validations.ts                | 51 -----------------
 src/shared/types/api.ts                      | 48 +++++++++-------
 9 files changed, 74 insertions(+), 151 deletions(-)

diff --git a/src/app/auth/callback/page.tsx b/src/app/auth/callback/page.tsx
index 54b603d..458492e 100644
--- a/src/app/auth/callback/page.tsx
+++ b/src/app/auth/callback/page.tsx
@@ -13,6 +13,7 @@ import { Loader2, AlertCircle, RefreshCcw } from "lucide-react"
 import { motion, AnimatePresence } from "framer-motion"
 import Link from "next/link"
 import { useI18n } from "@/shared/providers/locale-provider"
+import type { AuthMeResponse } from "@/shared/types/api"
 
 function RedirectHandler() {
   const { t } = useI18n()
@@ -46,7 +47,7 @@ function RedirectHandler() {
     hasCalledRef.current = true
 
     // 쿠키는 이미 Set-Cookie로 설정되어 있으므로, /auth/me로 사용자 식별 후 전체 정보 조회
-    apiClient.get<void, { username: string }>('/auth/me')
+    apiClient.get<void, AuthMeResponse>('/auth/me')
       .then(({ username }) => getUser(username))
       .then((user) => {
         login(user)
diff --git a/src/app/oauth2/redirect/page.tsx b/src/app/oauth2/redirect/page.tsx
index 2128b14..c967aa3 100644
--- a/src/app/oauth2/redirect/page.tsx
+++ b/src/app/oauth2/redirect/page.tsx
@@ -13,6 +13,7 @@ import { Loader2, AlertCircle, RefreshCcw } from "lucide-react"
 import { motion, AnimatePresence } from "framer-motion"
 import Link from "next/link"
 import { useI18n } from "@/shared/providers/locale-provider"
+import type { AuthMeResponse } from "@/shared/types/api"
 
 function RedirectHandler() {
   const { t } = useI18n()
@@ -46,7 +47,7 @@ function RedirectHandler() {
     hasCalledRef.current = true
 
     // 쿠키는 이미 Set-Cookie로 설정되어 있으므로, /auth/me로 사용자 식별 후 전체 정보 조회
-    apiClient.get<void, { username: string }>('/auth/me')
+    apiClient.get<void, AuthMeResponse>('/auth/me')
       .then(({ username }) => getUser(username))
       .then((user) => {
         login(user)
diff --git a/src/app/ranking/page.tsx b/src/app/ranking/page.tsx
index fe5087c..86382b4 100644
--- a/src/app/ranking/page.tsx
+++ b/src/app/ranking/page.tsx
@@ -4,7 +4,7 @@ import { useState, Suspense, useRef } from "react"
 import { useRouter, useSearchParams } from "next/navigation"
 import { LazyMotion, domAnimation, m } from "framer-motion"
 import { useRankingList } from "@/features/ranking/api/ranking-service"
-import { Tier } from "@/shared/types/api"
+import { Tier, TIER_VALUES } from "@/shared/types/api"
 import { getTierBadgeStyle, getTierDotColor } from "@/shared/constants/tier-styles"
 import { Avatar, AvatarFallback, AvatarImage } from "@/shared/components/avatar"
 import { Skeleton } from "@/shared/components/skeleton"
@@ -15,10 +15,7 @@ import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight, Search, Crown,
 import { cn } from "@/shared/lib/utils"
 import { useI18n } from "@/shared/providers/locale-provider"
 
-const TIERS: (Tier | 'ALL')[] = [
-    'ALL', 'CHALLENGER', 'MASTER', 'DIAMOND', 'EMERALD',
-    'PLATINUM', 'GOLD', 'SILVER', 'BRONZE', 'IRON'
-]
+const TIER_FILTERS: ReadonlyArray<Tier | 'ALL'> = ['ALL', ...TIER_VALUES]
 
 // [Component] Toolbar
 function RankingToolbar({
@@ -32,7 +29,7 @@ function RankingToolbar({
         <div className="sticky top-16 z-40 bg-background/80 backdrop-blur-xl border-b border-border/40 py-4 mb-8 transition-all">
             <div className="container max-w-5xl px-4 flex justify-center">
                 <div className="flex flex-wrap gap-2 justify-center">
-                    {TIERS.map((tier) => (
+                    {TIER_FILTERS.map((tier) => (
                         <button
                             key={tier}
                             onClick={() => onTierChange(tier)}
@@ -84,7 +81,8 @@ function RankingContent() {
     const pageParam = searchParams.get('page')
     const page = pageParam ? Math.max(0, parseInt(pageParam, 10) - 1) : 0
     const tierParam = searchParams.get('tier')
-    const selectedTier: Tier | 'ALL' = tierParam && TIERS.includes(tierParam as Tier) ? tierParam as Tier : 'ALL'
+    const selectedTier: Tier | 'ALL' =
+        tierParam && TIER_VALUES.includes(tierParam as Tier) ? (tierParam as Tier) : 'ALL'
 
 
 
diff --git a/src/app/sitemap.ts b/src/app/sitemap.ts
index 24d6ad8..0115a5b 100644
--- a/src/app/sitemap.ts
+++ b/src/app/sitemap.ts
@@ -1,58 +1,47 @@
 import { MetadataRoute } from "next"
+import type { ApiResponse, RankingListResponse, RankingUserInfo } from "@/shared/types/api"
 
 const BASE_URL = process.env.NEXT_PUBLIC_BASE_URL || "https://www.git-ranker.com"
 const API_URL = process.env.NEXT_PUBLIC_API_URL || "https://www.git-ranker.com"
 const SEO_LOCALES = ["en", "ko"] as const
 
-interface RankingUser {
-    username: string
-    tier: string
-    totalScore: number
-    profileImage: string
-}
+async function getRankingPage(page: number): Promise<RankingListResponse | null> {
+    const response = await fetch(`${API_URL}/api/v1/ranking?page=${page}&size=20`, {
+        next: { revalidate: 3600 },
+        headers: {
+            Accept: "application/json",
+        },
+    })
+
+    if (!response.ok) {
+        return null
+    }
 
-interface ApiResponse {
-    rankings?: RankingUser[]
-    pageInfo?: {
-        totalPages: number
-        totalElements: number
+    const payload = await response.json() as ApiResponse<RankingListResponse>
+    if (payload.result !== "SUCCESS" || !payload.data) {
+        return null
     }
+
+    return payload.data
 }
 
-async function getTopUsers(): Promise<RankingUser[]> {
+async function getTopUsers(): Promise<RankingUserInfo[]> {
     try {
         // First, get the first page to understand total pages
-        const firstPageResponse = await fetch(`${API_URL}/api/v1/ranking?page=0&size=20`, {
-            next: { revalidate: 3600 },
-            headers: {
-                'Accept': 'application/json',
-            }
-        })
-
-        if (!firstPageResponse.ok) {
+        const firstPageData = await getRankingPage(0)
+        if (!firstPageData) {
             return []
         }
 
-        const firstPageData: ApiResponse = await firstPageResponse.json()
-        const totalPages = Math.min(firstPageData.pageInfo?.totalPages || 1, 25) // Max 25 pages = 500 users
+        const totalPages = Math.min(firstPageData.pageInfo.totalPages || 1, 25) // Max 25 pages = 500 users
 
         // Fetch up to 500 users (25 pages x 20 users per page)
         const pages = Array.from({ length: totalPages }, (_, i) => i)
-        const responses = await Promise.all(
-            pages.map(page =>
-                fetch(`${API_URL}/api/v1/ranking?page=${page}&size=20`, {
-                    next: { revalidate: 3600 },
-                    headers: {
-                        'Accept': 'application/json',
-                    }
-                }).then(res => res.ok ? res.json() as Promise<ApiResponse> : null)
-                  .catch(() => null)
-            )
-        )
+        const responses = await Promise.all(pages.map((page) => getRankingPage(page).catch(() => null)))
 
-        const users: RankingUser[] = []
+        const users: RankingUserInfo[] = []
         for (const response of responses) {
-            if (response?.rankings) {
+            if (response) {
                 users.push(...response.rankings)
             }
         }
diff --git a/src/app/users/[username]/opengraph-image.tsx b/src/app/users/[username]/opengraph-image.tsx
index 86fa699..9c979b4 100644
--- a/src/app/users/[username]/opengraph-image.tsx
+++ b/src/app/users/[username]/opengraph-image.tsx
@@ -1,28 +1,16 @@
 import { ImageResponse } from 'next/og'
+import type { ApiResponse, RegisterUserResponse, Tier } from '@/shared/types/api'
 
 export const runtime = 'edge'
 export const alt = 'Git Ranker Profile'
 export const size = { width: 1200, height: 630 }
 export const contentType = 'image/png'
 
-interface UserData {
-    username: string
-    tier: string
-    totalScore: number
-    ranking: number
-    percentile: number
-    profileImage: string
-    commitCount: number
-    prCount: number
-    issueCount: number
-    reviewCount: number
-    mergedPrCount: number
-}
-
-const tierColors: Record<string, string> = {
+const tierColors: Record<Tier, string> = {
     CHALLENGER: '#dc2626',
     MASTER: '#7c3aed',
     DIAMOND: '#0ea5e9',
+    EMERALD: '#10b981',
     PLATINUM: '#06b6d4',
     GOLD: '#eab308',
     SILVER: '#64748b',
@@ -34,21 +22,23 @@ export default async function Image({ params }: { params: Promise<{ username: st
     const { username } = await params
     const apiUrl = process.env.NEXT_PUBLIC_API_URL || 'https://www.git-ranker.com'
 
-    let user: UserData | null = null
+    let user: RegisterUserResponse | null = null
 
     try {
         const response = await fetch(`${apiUrl}/api/v1/users/${username}`, {
             next: { revalidate: 3600 }
         })
         if (response.ok) {
-            const data = await response.json()
-            user = data.data || data.success
+            const payload = await response.json() as ApiResponse<RegisterUserResponse>
+            if (payload.result === 'SUCCESS' && payload.data) {
+                user = payload.data
+            }
         }
     } catch {
         // Fall back to default
     }
 
-    const accent = tierColors[user?.tier || ''] || '#6366f1'
+    const accent = user ? tierColors[user.tier] : '#6366f1'
 
     // User not found fallback
     if (!user) {
@@ -145,6 +135,7 @@ export default async function Image({ params }: { params: Promise<{ username: st
                         }}>
                             <img
                                 src={user.profileImage}
+                                alt={`${user.username} avatar`}
                                 width={80}
                                 height={80}
                                 style={{
diff --git a/src/shared/constants/tier-styles.ts b/src/shared/constants/tier-styles.ts
index e7084e0..c6c1c01 100644
--- a/src/shared/constants/tier-styles.ts
+++ b/src/shared/constants/tier-styles.ts
@@ -1,4 +1,4 @@
-import { Tier } from "@/shared/types/api"
+import { Tier, TIER_VALUES } from "@/shared/types/api"
 
 /**
  * Comprehensive tier styling system
@@ -147,10 +147,7 @@ export const TIER_TEXT_COLORS: Record<Tier | string, string> = {
 } as const
 
 // Ordered tier list (highest to lowest)
-export const TIER_ORDER: Tier[] = [
-    'CHALLENGER', 'MASTER', 'DIAMOND', 'EMERALD',
-    'PLATINUM', 'GOLD', 'SILVER', 'BRONZE', 'IRON'
-] as const
+export const TIER_ORDER: Tier[] = [...TIER_VALUES]
 
 // Helper functions
 export const getTierStyle = (tier: Tier | string) =>
diff --git a/src/shared/lib/api-client.ts b/src/shared/lib/api-client.ts
index 076d219..b42a304 100644
--- a/src/shared/lib/api-client.ts
+++ b/src/shared/lib/api-client.ts
@@ -1,19 +1,10 @@
 import axios, { AxiosError, InternalAxiosRequestConfig } from 'axios';
 import { removeLocalStorage } from './storage-cache';
 import { translate } from '@/shared/i18n/translate';
+import type { ApiResponse } from '@/shared/types/api';
 
 const API_BASE_URL = `${process.env.NEXT_PUBLIC_API_URL}/api/v1`;
 
-// 서버 에러 응답에서 메시지 추출
-export interface ApiErrorResponse {
-  result: 'ERROR';
-  data: null;
-  error: {
-    code: string;
-    message: string;
-  };
-}
-
 // 커스텀 에러 클래스 - 서버 에러 메시지 포함
 export class ApiError extends Error {
   code: string;
@@ -35,7 +26,7 @@ export const getErrorMessage = (error: unknown, fallback: string = translate('co
 
   if (axios.isAxiosError(error)) {
     // 서버 응답에서 에러 메시지 추출
-    const responseData = error.response?.data as ApiErrorResponse | undefined;
+    const responseData = error.response?.data as ApiResponse<unknown> | undefined;
     if (responseData?.error?.message) {
       return responseData.error.message;
     }
diff --git a/src/shared/lib/validations.ts b/src/shared/lib/validations.ts
index cc94b51..ce7256a 100644
--- a/src/shared/lib/validations.ts
+++ b/src/shared/lib/validations.ts
@@ -39,50 +39,6 @@ const createPageNumberSchema = () =>
 
 export const pageNumberSchema = createPageNumberSchema()
 
-// Tier validation
-export const tierSchema = z.enum([
-  "CHALLENGER",
-  "MASTER",
-  "DIAMOND",
-  "PLATINUM",
-  "GOLD",
-  "SILVER",
-  "BRONZE",
-  "IRON",
-])
-
-// API Response validation schemas
-export const userResponseSchema = z.object({
-  username: z.string(),
-  tier: tierSchema,
-  totalScore: z.number(),
-  ranking: z.number(),
-  percentile: z.number(),
-  profileImage: z.string().url(),
-  nodeId: z.string(),
-  lastFullScanAt: z.string().datetime(),
-})
-
-export const rankingItemSchema = z.object({
-  username: z.string(),
-  tier: tierSchema,
-  totalScore: z.number(),
-  ranking: z.number(),
-  profileImage: z.string().url(),
-})
-
-export const pageInfoSchema = z.object({
-  totalPages: z.number(),
-  totalElements: z.number(),
-  currentPage: z.number().optional(),
-  pageSize: z.number().optional(),
-})
-
-export const rankingResponseSchema = z.object({
-  rankings: z.array(rankingItemSchema),
-  pageInfo: pageInfoSchema.optional(),
-})
-
 // Validation helper functions
 export function validateGithubUsername(username: string): {
   success: boolean
@@ -119,10 +75,3 @@ export function validatePageNumber(page: number): {
   }
   return { success: false, error: result.error.issues[0]?.message }
 }
-
-// Type exports
-export type Tier = z.infer<typeof tierSchema>
-export type User = z.infer<typeof userResponseSchema>
-export type RankingItem = z.infer<typeof rankingItemSchema>
-export type PageInfo = z.infer<typeof pageInfoSchema>
-export type RankingResponse = z.infer<typeof rankingResponseSchema>
diff --git a/src/shared/types/api.ts b/src/shared/types/api.ts
index 55798b2..286caae 100644
--- a/src/shared/types/api.ts
+++ b/src/shared/types/api.ts
@@ -1,26 +1,35 @@
-export type Tier = 
-  | 'CHALLENGER' | 'MASTER' | 'DIAMOND' | 'EMERALD' 
-  | 'PLATINUM' | 'GOLD' | 'SILVER' | 'BRONZE' | 'IRON';
+// Manual contract mirror of `git-ranker/docs/openapi/openapi.json` until generated types are introduced.
+export const TIER_VALUES = [
+  'CHALLENGER',
+  'MASTER',
+  'DIAMOND',
+  'EMERALD',
+  'PLATINUM',
+  'GOLD',
+  'SILVER',
+  'BRONZE',
+  'IRON',
+] as const;
+
+export type Tier = (typeof TIER_VALUES)[number];
+export type UserRole = 'GUEST' | 'USER' | 'ADMIN';
+
+export interface ApiErrorPayload {
+  type: string;
+  message: string;
+  data?: unknown;
+}
 
-// 백엔드 실제 응답 구조
 export interface ApiResponse<T> {
   result: 'SUCCESS' | 'ERROR';
   data: T | null;
-  error: {
-    code: string;
-    message: string;
-  } | null;
+  error: ApiErrorPayload | null;
 }
 
-// 레거시 타입 (호환성 유지)
-export interface ApiResponseLegacy<T> {
-  resultType: 'SUCCESS' | 'ERROR';
-  error?: {
-    code: string;
-    message: string;
-    data?: unknown;
-  };
-  success?: T;
+export interface AuthMeResponse {
+  username: string;
+  profileImage: string;
+  role: UserRole;
 }
 
 export interface User {
@@ -30,7 +39,7 @@ export interface User {
   username: string;
   email: string | null;
   profileImage: string;
-  role: 'USER' | 'ADMIN';
+  role: UserRole;
   updatedAt: string;
   lastFullScanAt: string;
   totalScore: number;
@@ -50,8 +59,6 @@ export interface UserStats {
   diffPrCount: number;
   diffMergedPrCount: number;
   diffReviewCount: number;
-  // [Fix] 백엔드 응답 포맷 대응 (PascalCase fallback)
-  PrCount?: number;
 }
 
 export interface RegisterUserResponse extends User, UserStats {
@@ -79,4 +86,3 @@ export interface RankingListResponse {
   rankings: RankingUserInfo[];
   pageInfo: PageInfo;
 }
-

From bb10f60be9e40856d3e67f24ad6193d5e23600c1 Mon Sep 17 00:00:00 2001
From: hyoseok <alexization@gmail.com>
Date: Wed, 25 Mar 2026 10:23:23 +0900
Subject: [PATCH 2/2] =?UTF-8?q?fix:=20=EB=A6=AC=EB=B7=B0=20=EB=B0=98?=
 =?UTF-8?q?=EC=98=81=EC=9C=BC=EB=A1=9C=20=EA=B3=84=EC=95=BD=20=ED=8C=8C?=
 =?UTF-8?q?=EC=8B=B1=20=ED=9A=8C=EA=B7=80=20=EB=B0=A9=EC=A7=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- legacy 응답 fallback을 sitemap과 OG image에 복구
- 비정상 2xx API envelope를 ApiError로 처리
- tier 스타일 맵을 exhaustive typing으로 강화
---
 src/app/sitemap.ts                           | 66 +++++++++++++++++---
 src/app/users/[username]/opengraph-image.tsx | 63 ++++++++++++++++---
 src/shared/constants/tier-styles.ts          | 40 ++++++------
 src/shared/lib/api-client.ts                 |  7 +++
 src/shared/types/api.ts                      |  3 +
 5 files changed, 144 insertions(+), 35 deletions(-)

diff --git a/src/app/sitemap.ts b/src/app/sitemap.ts
index 0115a5b..87331a7 100644
--- a/src/app/sitemap.ts
+++ b/src/app/sitemap.ts
@@ -1,11 +1,58 @@
 import { MetadataRoute } from "next"
-import type { ApiResponse, RankingListResponse, RankingUserInfo } from "@/shared/types/api"
+import type { ApiResponse, RankingUserInfo } from "@/shared/types/api"
+import { isTier } from "@/shared/types/api"
 
 const BASE_URL = process.env.NEXT_PUBLIC_BASE_URL || "https://www.git-ranker.com"
 const API_URL = process.env.NEXT_PUBLIC_API_URL || "https://www.git-ranker.com"
 const SEO_LOCALES = ["en", "ko"] as const
 
-async function getRankingPage(page: number): Promise<RankingListResponse | null> {
+type SitemapRankingPage = {
+    rankings: RankingUserInfo[]
+    pageInfo: {
+        totalPages: number
+        totalElements: number
+    }
+}
+
+const isObjectRecord = (value: unknown): value is Record<string, unknown> =>
+    typeof value === "object" && value !== null
+
+const isRankingUserInfo = (value: unknown): value is RankingUserInfo =>
+    isObjectRecord(value) &&
+    typeof value.username === "string" &&
+    typeof value.profileImage === "string" &&
+    typeof value.ranking === "number" &&
+    typeof value.totalScore === "number" &&
+    typeof value.tier === "string" &&
+    isTier(value.tier)
+
+const isSitemapRankingPage = (value: unknown): value is SitemapRankingPage =>
+    isObjectRecord(value) &&
+    Array.isArray(value.rankings) &&
+    value.rankings.every(isRankingUserInfo) &&
+    isObjectRecord(value.pageInfo) &&
+    typeof value.pageInfo.totalPages === "number" &&
+    typeof value.pageInfo.totalElements === "number"
+
+const extractRankingPage = (payload: unknown): SitemapRankingPage | null => {
+    if (!isObjectRecord(payload)) {
+        return null
+    }
+
+    if ("result" in payload) {
+        return payload.result === "SUCCESS" && isSitemapRankingPage(payload.data)
+            ? payload.data
+            : null
+    }
+
+    if ("success" in payload) {
+        return isSitemapRankingPage(payload.success) ? payload.success : null
+    }
+
+    return isSitemapRankingPage(payload) ? payload : null
+}
+
+async function getRankingPage(page: number): Promise<SitemapRankingPage | null> {
     const response = await fetch(`${API_URL}/api/v1/ranking?page=${page}&size=20`, {
         next: { revalidate: 3600 },
         headers: {
@@ -17,12 +64,8 @@ async function getRankingPage(page: number): Promise<RankingListResponse | null>
         return null
     }
 
-    const payload = await response.json() as ApiResponse<RankingListResponse>
-    if (payload.result !== "SUCCESS" || !payload.data) {
-        return null
-    }
-
-    return payload.data
+    const payload = await response.json() as ApiResponse<SitemapRankingPage> | SitemapRankingPage | { success?: SitemapRankingPage }
+    return extractRankingPage(payload)
 }
 
 async function getTopUsers(): Promise<RankingUserInfo[]> {
@@ -36,8 +79,11 @@ async function getTopUsers(): Promise<RankingUserInfo[]> {
         const totalPages = Math.min(firstPageData.pageInfo.totalPages || 1, 25) // Max 25 pages = 500 users
 
         // Fetch up to 500 users (25 pages x 20 users per page)
-        const pages = Array.from({ length: totalPages }, (_, i) => i)
-        const responses = await Promise.all(pages.map((page) => getRankingPage(page).catch(() => null)))
+        const pages = Array.from({ length: Math.max(totalPages - 1, 0) }, (_, i) => i + 1)
+        const responses = [
+            firstPageData,
+            ...(await Promise.all(pages.map((page) => getRankingPage(page).catch(() => null)))),
+        ]
 
         const users: RankingUserInfo[] = []
         for (const response of responses) {
diff --git a/src/app/users/[username]/opengraph-image.tsx b/src/app/users/[username]/opengraph-image.tsx
index 9c979b4..6df4aba 100644
--- a/src/app/users/[username]/opengraph-image.tsx
+++ b/src/app/users/[username]/opengraph-image.tsx
@@ -1,5 +1,6 @@
 import { ImageResponse } from 'next/og'
-import type { ApiResponse, RegisterUserResponse, Tier } from '@/shared/types/api'
+import type { ApiResponse, Tier } from '@/shared/types/api'
+import { isTier } from '@/shared/types/api'
 
 export const runtime = 'edge'
 export const alt = 'Git Ranker Profile'
@@ -18,27 +19,75 @@ const tierColors: Record<Tier, string> = {
     IRON: '#71717a',
 }
 
+type OgUserData = {
+    username: string
+    tier: Tier
+    totalScore: number
+    ranking: number
+    percentile: number
+    profileImage: string
+    commitCount: number
+    prCount: number
+    issueCount: number
+    reviewCount: number
+    mergedPrCount: number
+}
+
+const isObjectRecord = (value: unknown): value is Record<string, unknown> =>
+    typeof value === 'object' && value !== null
+
+const isOgUserData = (value: unknown): value is OgUserData =>
+    isObjectRecord(value) &&
+    typeof value.username === 'string' &&
+    typeof value.tier === 'string' &&
+    isTier(value.tier) &&
+    typeof value.totalScore === 'number' &&
+    typeof value.ranking === 'number' &&
+    typeof value.percentile === 'number' &&
+    typeof value.profileImage === 'string' &&
+    typeof value.commitCount === 'number' &&
+    typeof value.prCount === 'number' &&
+    typeof value.issueCount === 'number' &&
+    typeof value.reviewCount === 'number' &&
+    typeof value.mergedPrCount === 'number'
+
+const extractUserData = (payload: unknown): OgUserData | null => {
+    if (!isObjectRecord(payload)) {
+        return null
+    }
+
+    if ('result' in payload) {
+        return payload.result === 'SUCCESS' && isOgUserData(payload.data)
+            ? payload.data
+            : null
+    }
+
+    if ('success' in payload) {
+        return isOgUserData(payload.success) ? payload.success : null
+    }
+
+    return isOgUserData(payload) ? payload : null
+}
+
 export default async function Image({ params }: { params: Promise<{ username: string }> }) {
     const { username } = await params
     const apiUrl = process.env.NEXT_PUBLIC_API_URL || 'https://www.git-ranker.com'
 
-    let user: RegisterUserResponse | null = null
+    let user: OgUserData | null = null
 
     try {
         const response = await fetch(`${apiUrl}/api/v1/users/${username}`, {
             next: { revalidate: 3600 }
         })
         if (response.ok) {
-            const payload = await response.json() as ApiResponse<RegisterUserResponse>
-            if (payload.result === 'SUCCESS' && payload.data) {
-                user = payload.data
-            }
+            const payload = await response.json() as ApiResponse<OgUserData> | OgUserData | { success?: OgUserData }
+            user = extractUserData(payload)
         }
     } catch {
         // Fall back to default
     }
 
-    const accent = user ? tierColors[user.tier] : '#6366f1'
+    const accent = user ? tierColors[user.tier] ?? '#6366f1' : '#6366f1'
 
     // User not found fallback
     if (!user) {
diff --git a/src/shared/constants/tier-styles.ts b/src/shared/constants/tier-styles.ts
index c6c1c01..50c51d9 100644
--- a/src/shared/constants/tier-styles.ts
+++ b/src/shared/constants/tier-styles.ts
@@ -1,12 +1,11 @@
-import { Tier, TIER_VALUES } from "@/shared/types/api"
+import { isTier, Tier, TIER_VALUES } from "@/shared/types/api"
 
 /**
  * Comprehensive tier styling system
  * Centralized to prevent duplication and ensure consistency
  */
 
-// Full tier styles for profile pages and detailed views
-export const TIER_STYLES: Record<Tier | string, {
+type TierStyle = {
     bgGradient: string;
     border: string;
     text: string;
@@ -14,7 +13,10 @@ export const TIER_STYLES: Record<Tier | string, {
     shadow: string;
     iconColor: string;
     overlay?: string;
-}> = {
+}
+
+// Full tier styles for profile pages and detailed views
+export const TIER_STYLES: Record<Tier, TierStyle> = {
     CHALLENGER: {
         bgGradient: "from-red-500/10 via-orange-500/5 to-background",
         border: "border-red-500/30",
@@ -95,7 +97,7 @@ export const TIER_STYLES: Record<Tier | string, {
 } as const
 
 // Simplified tier color styles for badges and compact views
-export const TIER_COLOR_STYLES: Record<Tier | string, string> = {
+export const TIER_COLOR_STYLES: Record<Tier, string> = {
     CHALLENGER: "bg-red-500/10 text-red-500 border-red-500/30",
     MASTER: "bg-purple-500/10 text-purple-500 border-purple-500/30",
     DIAMOND: "bg-sky-500/10 text-sky-500 border-sky-500/30",
@@ -108,7 +110,7 @@ export const TIER_COLOR_STYLES: Record<Tier | string, string> = {
 } as const
 
 // Badge styles for ranking list (light/dark mode support)
-export const TIER_BADGE_STYLES: Record<Tier | string, string> = {
+export const TIER_BADGE_STYLES: Record<Tier, string> = {
     CHALLENGER: "bg-red-100 text-red-600 dark:bg-red-900/40 dark:text-red-400 border-red-200 dark:border-red-800",
     MASTER: "bg-purple-100 text-purple-600 dark:bg-purple-900/40 dark:text-purple-400 border-purple-200 dark:border-purple-800",
     DIAMOND: "bg-sky-100 text-sky-600 dark:bg-sky-900/40 dark:text-sky-400 border-sky-200 dark:border-sky-800",
@@ -121,7 +123,7 @@ export const TIER_BADGE_STYLES: Record<Tier | string, string> = {
 } as const
 
 // Tier dot colors for mobile view and indicators
-export const TIER_DOT_COLORS: Record<Tier | string, string> = {
+export const TIER_DOT_COLORS: Record<Tier, string> = {
     CHALLENGER: "bg-red-500",
     MASTER: "bg-purple-500",
     DIAMOND: "bg-sky-500",
@@ -134,7 +136,7 @@ export const TIER_DOT_COLORS: Record<Tier | string, string> = {
 } as const
 
 // Text-only tier colors for modals and simple displays
-export const TIER_TEXT_COLORS: Record<Tier | string, string> = {
+export const TIER_TEXT_COLORS: Record<Tier, string> = {
     CHALLENGER: "text-red-500",
     MASTER: "text-purple-500",
     DIAMOND: "text-blue-500",
@@ -149,18 +151,20 @@ export const TIER_TEXT_COLORS: Record<Tier | string, string> = {
 // Ordered tier list (highest to lowest)
 export const TIER_ORDER: Tier[] = [...TIER_VALUES]
 
+const normalizeTier = (tier: string): Tier => (isTier(tier) ? tier : 'IRON')
+
 // Helper functions
-export const getTierStyle = (tier: Tier | string) =>
-    TIER_STYLES[tier] || TIER_STYLES['IRON']
+export const getTierStyle = (tier: string) =>
+    TIER_STYLES[normalizeTier(tier)]
 
-export const getTierColorClass = (tier: Tier | string) =>
-    TIER_COLOR_STYLES[tier] || TIER_COLOR_STYLES['IRON']
+export const getTierColorClass = (tier: string) =>
+    TIER_COLOR_STYLES[normalizeTier(tier)]
 
-export const getTierDotColor = (tier: Tier | string) =>
-    TIER_DOT_COLORS[tier] || TIER_DOT_COLORS['IRON']
+export const getTierDotColor = (tier: string) =>
+    TIER_DOT_COLORS[normalizeTier(tier)]
 
-export const getTierTextColor = (tier: Tier | string) =>
-    TIER_TEXT_COLORS[tier] || TIER_TEXT_COLORS['IRON']
+export const getTierTextColor = (tier: string) =>
+    TIER_TEXT_COLORS[normalizeTier(tier)]
 
-export const getTierBadgeStyle = (tier: Tier | string) =>
-    TIER_BADGE_STYLES[tier] || TIER_BADGE_STYLES['IRON']
+export const getTierBadgeStyle = (tier: string) =>
+    TIER_BADGE_STYLES[normalizeTier(tier)]
diff --git a/src/shared/lib/api-client.ts b/src/shared/lib/api-client.ts
index b42a304..edc80a5 100644
--- a/src/shared/lib/api-client.ts
+++ b/src/shared/lib/api-client.ts
@@ -94,6 +94,13 @@ apiClient.interceptors.response.use(
     if (response.data?.result === 'SUCCESS') {
       return response.data.data;
     }
+    if (response.data?.result === 'ERROR') {
+      throw new ApiError(
+        response.data.error?.message ?? translate('common.error'),
+        response.data.error?.type ?? 'UNKNOWN_ERROR',
+        response.status
+      );
+    }
     // Fallback: 기존 구조도 지원
     return response.data?.success ?? response.data;
   },
diff --git a/src/shared/types/api.ts b/src/shared/types/api.ts
index 286caae..cdc99d1 100644
--- a/src/shared/types/api.ts
+++ b/src/shared/types/api.ts
@@ -14,6 +14,9 @@ export const TIER_VALUES = [
 export type Tier = (typeof TIER_VALUES)[number];
 export type UserRole = 'GUEST' | 'USER' | 'ADMIN';
 
+export const isTier = (value: string): value is Tier =>
+  (TIER_VALUES as readonly string[]).includes(value);
+
 export interface ApiErrorPayload {
   type: string;
   message: string;