에러 코드 및 상태 참조
Smart Money API의 에러 코드, HTTP 상태 코드 및 문제 해결 단계에 대한 종합 가이드. 에러 응답을 이해하고 통합 문제를 빠르게 해결하세요.
2xx 성공 코드
성공 응답은 요청이 성공적으로 처리되었음을 나타냅니다.
| 코드 | 상태 | 의미 |
|---|---|---|
| 200 | OK | 요청이 성공했습니다. 응답 본문에 요청된 데이터가 포함되어 있습니다. |
| 201 | Created | 리소스가 성공적으로 생성되었습니다. 응답에 새 리소스가 포함됩니다. |
| 204 | No Content | 요청이 성공했지만 반환할 콘텐츠가 없습니다 (예: DELETE). |
200 응답 예시
JSON
{
"success": true,
"data": {
"total": 42,
"positions": [...],
"pagination": {
"page": 1,
"limit": 50
}
},
"timestamp": "2026-03-21T14:35:22Z"
}
4xx 클라이언트 오류 코드
클라이언트 오류는 요청이 잘못되었거나 유효하지 않음을 나타냅니다. 요청을 수정하고 다시 시도하세요.
| 코드 | 상태 | 원인 |
|---|---|---|
| 400 | Bad Request | 잘못된 요청 구문. 쿼리 매개변수, 헤더 및 요청 본문을 확인하세요. |
| 401 | Unauthorized | 누락되었거나 유효하지 않은 인증 자격 증명. API 키 또는 JWT 토큰을 확인하세요. |
| 402 | Payment Required | 구독 결제가 실패했습니다. 계정에서 결제 정보를 업데이트하세요. |
| 403 | Forbidden | 인증되었지만 이 리소스에 대한 권한이 없습니다. 귀하의 요금제에는 이 기능이 포함되어 있지 않습니다. |
| 404 | Not Found | 리소스가 존재하지 않습니다. 엔드포인트 URL과 매개변수를 확인하세요. |
| 429 | Too Many Requests | 속도 제한을 초과했습니다. 다시 시도하기 전에 기다리세요. Retry-After 헤더를 확인하세요. |
| 422 | Unprocessable Entity | 유효성 검사 실패. 요청 매개변수가 유효하지 않거나 필수 필드가 누락되었습니다. |
인증 오류 예시
API 키 누락 (401)
JSON
{
"success": false,
"error": {
"code": "AUTH_MISSING_KEY",
"message": "인증 자격 증명이 제공되지 않았습니다.",
"resolution": "Authorization 헤더에 API 키를 포함하세요: Authorization: Bearer sk_live_..."
},
"timestamp": "2026-03-21T14:35:22Z"
}
유효하지 않은 API 키 (401)
JSON
{
"success": false,
"error": {
"code": "AUTH_INVALID_KEY",
"message": "유효하지 않거나 만료된 API 키입니다.",
"resolution": "콘솔에서 새 API 키를 생성하세요: https://smartmoneyapi.com/console"
},
"timestamp": "2026-03-21T14:35:22Z"
}
속도 제한 (429)
API 할당량을 초과하면 서버가 429 Too Many Requests를 반환합니다. 응답 헤더에서 속도 제한 정보를 확인하세요:
HTTP 헤더
X-Requests-Remaining: 0
X-Requests-Limit: 200
X-Requests-Reset: 1711116922
Retry-After: 3600
속도 제한 오류 응답
JSON
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "일일 API 요청 한도(10)를 초과했습니다.",
"resolution": "Trader ($29/월, 400 요청/일) 또는 Pro ($79/월, 4,000 요청/일) 요금제로 업그레이드하세요.",
"reset_at": "2026-03-22T09:00:00Z"
},
"timestamp": "2026-03-21T14:35:22Z"
}
유효성 검사 오류 (422)
유효성 검사 오류는 요청 매개변수가 유효하지 않거나 필수 필드가 누락되었을 때 발생합니다.
JSON
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "요청 유효성 검사 실패.",
"details": [
{
"field": "symbol",
"error": "유효하지 않은 거래 쌍. 예상 형식: BTCUSDT"
},
{
"field": "min_position_size",
"error": "양수여야 합니다"
}
],
"resolution": "유효성 검사 오류를 수정하고 다시 시도하세요."
},
"timestamp": "2026-03-21T14:35:22Z"
}
5xx 서버 오류 코드
서버 오류는 우리 측의 문제를 나타냅니다. 이러한 오류는 일시적이며 일반적으로 빠르게 해결됩니다. 지수 백오프 재시도 로직을 구현하세요.
| 코드 | 상태 | 조치 |
|---|---|---|
| 500 | Internal Error | 예기치 않은 서버 오류. 지수 백오프로 재시도하세요. |
| 502 | Bad Gateway | 일시적인 서비스 중단. 몇 초 후에 다시 시도하세요. |
| 503 | Service Unavailable | 유지보수 또는 일시적인 중단. 상태 페이지를 확인하세요. Retry-After 간격 후에 다시 시도하세요. |
| 504 | Gateway Timeout | 요청이 너무 오래 걸렸습니다. 서버가 이미 처리했을 수 있습니다. 멱등성을 확인하세요. |
서버 오류 예시 (503)
JSON
{
"success": false,
"error": {
"code": "SERVICE_UNAVAILABLE",
"message": "유지보수로 인해 서비스가 일시적으로 사용 불가능합니다.",
"resolution": "5분 후에 다시 시도하세요. 상태를 확인하세요: https://status.smartmoneyapi.com"
},
"timestamp": "2026-03-21T14:35:22Z"
}
문제 해결 가이드
401 Unauthorized - 유효하지 않은 API 키
문제: API 키가 있음에도 401 오류가 발생합니다.
해결 방법:
- API 키가 "Bearer" 접두사와 함께 Authorization 헤더에 포함되어 있는지 확인하세요
- API 키가 만료되거나 취소되지 않았는지 확인하세요
- 올바른 키(프로덕션, 스테이징 또는 개발)를 사용 중인지 확인하세요
- 현재 키를 분실한 경우 콘솔에서 새 API 키를 생성하세요
403 Forbidden - 기능 사용 불가
문제: 특정 엔드포인트에서 403 오류가 발생합니다.
해결 방법:
- API 티어를 확인하세요. 일부 엔드포인트는 Trader 또는 Pro 요금제가 필요합니다
- 프리미엄 기능에 액세스하려면 /pricing.html에서 요금제를 업그레이드하세요
- API 키에 필요한 범위가 활성화되어 있는지 확인하세요
- 액세스 권한이 있어야 한다고 생각되면 지원팀에 문의하세요
429 Too Many Requests - 속도 제한
문제: 429 오류가 발생하고 속도 제한이 적용됩니다.
해결 방법:
- 지수 백오프 재시도 로직을 구현하세요 (1초, 2초, 4초 등 기다림)
- 중복 API 호출을 피하기 위해 응답을 캐시하세요
- 실시간 데이터를 위해 REST 엔드포인트 폴링 대신 WebSocket을 사용하세요
- 더 높은 할당량을 위해 요금제를 업그레이드하세요 (Trader 1,000/일, Pro 5,000/일)
- 여러 쿼리를 단일 요청으로 묶어 가능한 경우 처리하세요
400 Bad Request - 유효하지 않은 매개변수
문제: 잘못된 요청으로 400 오류가 발생합니다.
해결 방법:
- 필수 및 선택적 매개변수에 대한 API 문서를 확인하세요
- 매개변수 유형(문자열 vs 숫자, 배열 vs 객체)을 확인하세요
- JSON이 유효하고 올바르게 형식화되었는지 확인하세요
- 적절한 경로 매개변수와 함께 올바른 엔드포인트 URL을 사용하세요
- 쿼리 매개변수 이름에 오타가 있는지 확인하세요
5xx 서버 오류 - 일시적인 중단
문제: 500, 502, 503 또는 504 오류 발생
해결 방법:
- https://status.smartmoneyapi.com에서 서비스 상태 확인
- 지수 백오프를 사용한 자동 재시도 구현 (최대 5-10회 시도)
- 503 오류 재시도 전 30-60초 대기
- Retry-After 헤더를 사용하여 재시도 타이밍 결정
- 상태 페이지 구독으로 인시던트 알림 받기
오류 응답 형식
모든 오류 응답은 일관된 형식을 따릅니다:
JSON
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "사람이 읽을 수 있는 오류 메시지",
"details": {...},
"resolution": "문제 해결 단계"
},
"timestamp": "2026-03-21T14:35:22Z"
}