OPERATIONS
에러 코드
불리자 API 가 반환하는 에러 코드와 권장 대응 방법이에요. 모든 에러 응답은 { "error": "...", "message": "..." } 형식이고, 일부는 Retry-After 헤더가 함께 와요.
인증 에러
| 상태 코드 | 에러 코드 | 에러 메시지 | 해결 방법 |
|---|---|---|---|
| 401 | NO_KEY | Authorization: Bearer rfk_live_... 헤더가 필요합니다. | Authorization 헤더 추가 |
| 401 | INVALID_KEY | API 키가 유효하지 않거나 폐기되었습니다. | 키 형식(rfk_live_<48 hex>) 확인 후 새로 발급 |
한도 에러
| 상태 코드 | 에러 코드 | 에러 메시지 | 해결 방법 |
|---|---|---|---|
| 429 | RPM_EXCEEDED | 분당 한도 N 회 초과. | Retry-After 헤더만큼 대기 후 재시도 |
| 429 | DAILY_QUOTA_EXCEEDED | 일일 한도 N 회 초과. | KST 자정 리셋 대기 또는 한+미 구독으로 무제한 전환 |
리소스 에러
| 상태 코드 | 에러 코드 | 에러 메시지 | 해결 방법 |
|---|---|---|---|
| 400 | BAD_REQUEST | 파라미터 형식 오류 (예: from = YYYY-MM) | 쿼리 파라미터 형식 점검 |
| 404 | STOCK_NOT_FOUND | 종목을 찾을 수 없습니다. | 종목 코드 확인 (KR 6자리, US 티커) |
서버 에러
| 상태 코드 | 에러 코드 | 에러 메시지 | 해결 방법 |
|---|---|---|---|
| 502 | UPSTREAM_DOWN | 내부 데이터 서비스가 응답하지 않습니다. | 잠시 후 재시도 (자동 복구) |
| 502 | UPSTREAM_ERROR | upstream <상태코드> | 잠시 후 재시도. 지속 시 status.richgo.ai 확인 |
| 500 | DB_ERROR | DB 작업 실패 | 재시도. 지속 시 support 문의 |
재시도 정책
권장 재시도 전략은 다음과 같아요.
- 4xx 에러(401·404·400): 자동 재시도하지 않아요. 코드를 고친 후 다시 호출.
- 429:
Retry-After헤더 값(초)만큼 대기 후 재시도. - 5xx 에러: exponential backoff 권장 — 1초, 2초, 4초, 8초 (최대 3회).
에러 응답 예시
json
// 401 NO_KEY
{
"error": "NO_KEY",
"message": "Authorization: Bearer rfk_live_... 헤더가 필요합니다."
}
// 429 DAILY_QUOTA_EXCEEDED (Retry-After: 14400 헤더 포함)
{
"error": "DAILY_QUOTA_EXCEEDED",
"message": "일일 한도 1000 회 초과. 한+미 구독으로 무제한 전환 가능합니다."
}
// 404 STOCK_NOT_FOUND
{
"error": "STOCK_NOT_FOUND",
"message": "종목을 찾을 수 없습니다."
}에러 추적이 필요하면
에러 응답이 발생할 때 요청 URL · 키 prefix · 타임스탬프를 같이 로깅하면 좋아요. 키 prefix (
rfk_live_xxx)만으로 어떤 키였는지 식별 가능해요.