에러 코드 레퍼런스
Destiny Engine API에서 반환되는 HTTP 상태 코드와 에러 메시지를 설명합니다. 각 에러에 대한 원인과 해결 방법을 확인하세요.
HTTP 상태 코드
API는 표준 HTTP 상태 코드를 사용하여 요청의 성공 또는 실패를 나타냅니다.
성공 응답
| 상태 코드 | 의미 | 설명 |
|---|---|---|
| 200 OK | 요청 성공 | 요청이 성공적으로 처리되었고 응답 데이터가 반환되었습니다. |
클라이언트 에러 (4xx)
| 상태 코드 | 의미 | 설명 |
|---|---|---|
| 400 Bad Request | 잘못된 요청 | 요청 파라미터가 잘못되었거나 유효하지 않습니다. 요청 데이터의 형식과 값을 확인하세요. |
| 401 Unauthorized | 인증 실패 | API 키가 유효하지 않거나 제공되지 않았습니다. X-API-Key 헤더를 확인하세요. |
| 403 Forbidden | 접근 거부 | 현재 플랜에서 해당 기능을 사용할 수 없습니다. 플랜 업그레이드가 필요할 수 있습니다. |
| 404 Not Found | 찾을 수 없음 | 요청한 리소스를 찾을 수 없습니다. 엔드포인트 URL과 요청 경로를 확인하세요. |
| 422 Unprocessable Entity | 처리 불가능한 엔티티 | 요청 형식은 올바르지만 필수 필드가 누락되었거나 데이터 타입이 일치하지 않습니다. |
| 429 Too Many Requests | 요청 제한 초과 | 사용량 한도를 초과했습니다. 리셋 시간을 대기하거나 플랜을 업그레이드하세요. |
서버 에러 (5xx)
| 상태 코드 | 의미 | 설명 |
|---|---|---|
| 500 Internal Server Error | 내부 서버 오류 | 서버에서 예상치 못한 오류가 발생했습니다. 지속되는 경우 지원팀에 문의하세요. |
에러 응답 형식
모든 에러 응답은 다음과 같은 JSON 형식을 따릅니다:
{
"detail": "에러 메시지"
}또는 success 필드를 포함하는 경우:
{
"success": false,
"error": "에러 메시지"
}일반적인 에러
인증 에러
| 에러 메시지 | 상태 코드 | 원인 | 해결 방법 |
|---|---|---|---|
| Invalid API key | 401 | 제공된 API 키가 유효하지 않음 | 개발자 포털에서 API 키를 확인하고 X-API-Key 헤더에 올바른 키를 포함했는지 확인 |
| Usage limit exceeded | 429 | 플랜의 월간 사용량 한도를 초과 | 다음 달 리셋을 대기하거나 상위 플랜으로 업그레이드 |
| Access denied. Feature '...' not available in your plan. | 403 | 현재 플랜에서 해당 기능 미지원 | 해당 기능을 포함하는 플랜으로 업그레이드 |
유효성 검증 에러
Natal Chart API
| 에러 메시지 | 상태 코드 | 원인 | 해결 방법 |
|---|---|---|---|
| Invalid datetime format | 400 | 날짜/시간 형식이 잘못됨 | ISO 8601 형식 (YYYY-MM-DDTHH:MM:SS) 사용 |
| Latitude must be between -90 and 90 | 400 | 위도 값이 범위를 벗어남 | 위도는 -90 ~ 90 사이의 값 사용 |
| Longitude must be between -180 and 180 | 400 | 경도 값이 범위를 벗어남 | 경도는 -180 ~ 180 사이의 값 사용 |
| Invalid house system | 400 | 지원하지 않는 하우스 시스템 | PLACIDUS, KOCH, WHOLE_SIGN, EQUAL, CAMPANUS, REGIOMONTANUS 중 선택 |
Saju API
| 에러 메시지 | 상태 코드 | 원인 | 해결 방법 |
|---|---|---|---|
| 음력 변환 실패 | 400 | 음력 날짜를 양력으로 변환할 수 없음 | 유효한 음력 날짜인지 확인 (1900-2100년 범위) |
| gender must be M or F | 400 | 성별 값이 올바르지 않음 | gender 필드에 'M' 또는 'F' 입력 |
Jami API
| 에러 메시지 | 상태 코드 | 원인 | 해결 방법 |
|---|---|---|---|
| Invalid lunar date provided. | 400 | 음력 날짜를 양력으로 변환할 수 없음 | 유효한 음력 날짜인지 확인 (1900-2100년 범위) |
| Cannot convert solar date to lunar date. | 400 | 양력 날짜를 음력으로 변환할 수 없음 | 유효한 양력 날짜인지 확인 |
| Missing required fields: ... | 422 | 필수 필드가 누락됨 | 에러 메시지에 표시된 필드를 요청에 포함 |
| Field '...' must be an integer. | 422 | 필드 타입이 일치하지 않음 | 해당 필드에 정수 값 입력 |
| No valid birth date candidates found | 404 | 역추론 결과 유효한 생년월일시를 찾을 수 없음 | 입력한 차트 정보가 정확한지 확인 |
서버 에러
| 에러 메시지 | 상태 코드 | 원인 | 해결 방법 |
|---|---|---|---|
| Error during calculation | 500 | 계산 중 예상치 못한 오류 발생 | 입력 데이터를 확인하고 문제가 지속되면 support@destinyapi.com으로 문의 |
| Internal server error | 500 | 서버 내부 오류 | 잠시 후 재시도하고 문제가 지속되면 지원팀에 문의 |
문제 해결 가이드
1. API 키 관련 문제
증상: 401 Unauthorized 에러
체크리스트:
- API 키가
X-API-Key헤더에 포함되어 있는가? - API 키를 복사할 때 앞뒤 공백이 포함되지 않았는가?
- 개발자 포털에서 API 키가 활성화 상태인가?
- 올바른 환경(개발/프로덕션)의 API 키를 사용하고 있는가?
2. 사용량 제한 문제
증상: 429 Too Many Requests 에러
해결 방법:
- 즉시 해결: 캐싱을 도입하여 불필요한 API 호출 줄이기
- 단기: 다음 달 리셋 시간 확인 (매월 1일 00:00 UTC)
- 장기: 상위 플랜으로 업그레이드
3. 날짜/시간 형식 문제
증상: 400 Bad Request with "Invalid datetime format"
올바른 형식:
- Natal Chart API:
YYYY-MM-DDTHH:MM:SS(예: 2024-03-15T14:30:00) - Saju API:
YYYY-MM-DD(날짜),HH:MM(시간) - Jami API:
YYYY-MM-DD(날짜),HH:MM(시간)
4. 음력 변환 문제
증상: "음력 변환 실패" 에러
가능한 원인:
- 1900년 이전 또는 2100년 이후의 날짜 입력
- 존재하지 않는 음력 날짜 (예: 2월 30일)
- 윤달 여부가 잘못 설정됨
에러 처리 모범 사례
클라이언트 측 구현 예시
JavaScript
async function callAPI() {
try {
const response = await fetch('https://api.destinyapi.com/v1/astrology/natal-chart', {
method: 'POST',
headers: {
'X-API-Key': 'your_api_key',
'Content-Type': 'application/json',
},
body: JSON.stringify(data),
});
if (!response.ok) {
const error = await response.json();
switch (response.status) {
case 400:
console.error('잘못된 요청:', error.detail);
// 사용자에게 입력 데이터 확인 요청
break;
case 401:
console.error('인증 실패:', error.detail);
// API 키 재확인 또는 갱신
break;
case 429:
console.error('사용량 초과:', error.detail);
// 재시도 로직 또는 상위 플랜 안내
break;
default:
console.error('서버 에러:', error.detail);
}
return null;
}
return await response.json();
} catch (error) {
console.error('네트워크 에러:', error);
return null;
}
}Python
import requests
def call_api(data):
try:
response = requests.post(
'https://api.destinyapi.com/v1/astrology/natal-chart',
headers={'X-API-Key': 'your_api_key'},
json=data
)
if response.status_code == 200:
return response.json()
error = response.json()
if response.status_code == 400:
print(f"잘못된 요청: {error['detail']}")
elif response.status_code == 401:
print(f"인증 실패: {error['detail']}")
elif response.status_code == 429:
print(f"사용량 초과: {error['detail']}")
else:
print(f"서버 에러: {error['detail']}")
return None
except requests.exceptions.RequestException as e:
print(f"네트워크 에러: {e}")
return None지원팀 문의
위 문제 해결 방법으로 해결되지 않는 경우, 다음 정보와 함께 지원팀에 문의하세요:
- 발생한 에러 메시지 (전체 응답 포함)
- 요청한 엔드포인트 URL
- 요청 파라미터 (민감한 정보 제외)
- 발생 시간 (타임존 포함)
- 사용 중인 API 키의 플랜