docs: Alpaca 100-symbol batch limit — endpoint description + 502 error msg

Both GET /price/data and GET /alpaca/intraday:
- description에 배치 제한 설명 추가 (100개/요청, 자동 분할, 응답시간 선형 증가)
- 502 에러 메시지에 심볼 수 초과 가능성 힌트 추가

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

app/api/v1/endpoints/alpaca.py

@@ -242,7 +242,12 @@ async def get_alpaca_price_data(
         "- `tickers`: comma-separated list, e.g. `AAPL,MSFT,BF-B`\n"
         "- `interval`: `1m`, `5m`, `15m`, `30m`, `1h` (또는 `5min`, `15min` 등)\n"
         "- DB 저장 후 재요청 시 Alpaca 미사용\n"
-        "- Requires `ALPACA_API_KEY` / `ALPACA_SECRET_KEY`."
+        "- Requires `ALPACA_API_KEY` / `ALPACA_SECRET_KEY`.\n\n"
+        "**⚠️ Alpaca 배치 제한**\n\n"
+        "Alpaca multi-bar 엔드포인트는 요청당 **~100개 심볼**이 실질적 상한입니다 "
+        "(공식 문서 미명시, 커뮤니티 보고 및 실제 운용 기준 — 초과 시 502 발생). "
+        "내부적으로 **100개 단위로 자동 분할**하여 요청하므로 클라이언트는 신경 쓸 필요 없음. "
+        "단, 배치 수가 늘어날수록 응답 시간이 선형적으로 증가함 (500종목 → Alpaca 5회 호출)."
     ),
 )
 async def get_alpaca_intraday_multi(
@@ -273,7 +278,14 @@ async def get_alpaca_intraday_multi(
             db, symbols, start_dt, end_dt, interval, force_refresh
         )
     except Exception as e:
-        raise HTTPException(status_code=502, detail=f"Alpaca API error: {e}")
+        err = str(e)
+        detail = f"Alpaca API error: {err}"
+        if "502" in err or "Bad Gateway" in err:
+            detail = (
+                f"Alpaca 502 Bad Gateway — 요청당 심볼 수 초과 가능성. "
+                f"내부 배치 크기: 100개/요청. 원인: {err}"
+            )
+        raise HTTPException(status_code=502, detail=detail)
     finally:
         await svc.client.close()
 

app/api/v1/endpoints/price.py

@@ -299,7 +299,12 @@ async def get_price_data(
         "- Ticker normalization: `BF-B` → `BF.B` handled automatically; "
         "response keys use the original symbol names.\n"
         "- `force_refresh=true`: re-fetch all from Alpaca regardless of DB state.\n"
-        "- Requires `ALPACA_API_KEY` / `ALPACA_SECRET_KEY`."
+        "- Requires `ALPACA_API_KEY` / `ALPACA_SECRET_KEY`.\n\n"
+        "**⚠️ Alpaca 배치 제한**\n\n"
+        "Alpaca multi-bar 엔드포인트는 요청당 **~100개 심볼**이 실질적 상한입니다 "
+        "(공식 문서 미명시, 커뮤니티 보고 및 실제 운용 기준). "
+        "내부적으로 **100개 단위로 자동 분할**하여 요청하므로 클라이언트는 신경 쓸 필요 없음. "
+        "단, 배치 수가 늘어날수록 응답 시간이 선형적으로 증가함 (500종목 → Alpaca 5회 호출)."
     ),
     tags=["price", "alpaca"],
 )
@@ -330,7 +335,14 @@ async def get_multi_ticker_daily_bars(
             db, symbols, start_dt, end_dt, interval, force_refresh
         )
     except Exception as e:
-        raise HTTPException(status_code=502, detail=f"Alpaca API error: {e}")
+        err = str(e)
+        detail = f"Alpaca API error: {err}"
+        if "502" in err or "Bad Gateway" in err:
+            detail = (
+                f"Alpaca 502 Bad Gateway — 요청당 심볼 수 초과 가능성. "
+                f"내부 배치 크기: 100개/요청. 원인: {err}"
+            )
+        raise HTTPException(status_code=502, detail=detail)
     finally:
         await svc.client.close()