DESTINYAPI · Developer Portal

에러 코드 레퍼런스

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 key401제공된 API 키가 유효하지 않음개발자 포털에서 API 키를 확인하고 X-API-Key 헤더에 올바른 키를 포함했는지 확인
Usage limit exceeded429플랜의 월간 사용량 한도를 초과다음 달 리셋을 대기하거나 상위 플랜으로 업그레이드
Access denied. Feature '...' not available in your plan.403현재 플랜에서 해당 기능 미지원해당 기능을 포함하는 플랜으로 업그레이드

유효성 검증 에러

Natal Chart API

에러 메시지상태 코드원인해결 방법
Invalid datetime format400날짜/시간 형식이 잘못됨ISO 8601 형식 (YYYY-MM-DDTHH:MM:SS) 사용
Latitude must be between -90 and 90400위도 값이 범위를 벗어남위도는 -90 ~ 90 사이의 값 사용
Longitude must be between -180 and 180400경도 값이 범위를 벗어남경도는 -180 ~ 180 사이의 값 사용
Invalid house system400지원하지 않는 하우스 시스템PLACIDUS, KOCH, WHOLE_SIGN, EQUAL, CAMPANUS, REGIOMONTANUS 중 선택

Saju API

에러 메시지상태 코드원인해결 방법
음력 변환 실패400음력 날짜를 양력으로 변환할 수 없음유효한 음력 날짜인지 확인 (1900-2100년 범위)
gender must be M or F400성별 값이 올바르지 않음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 found404역추론 결과 유효한 생년월일시를 찾을 수 없음입력한 차트 정보가 정확한지 확인

서버 에러

에러 메시지상태 코드원인해결 방법
Error during calculation500계산 중 예상치 못한 오류 발생입력 데이터를 확인하고 문제가 지속되면 support@destinyapi.com으로 문의
Internal server error500서버 내부 오류잠시 후 재시도하고 문제가 지속되면 지원팀에 문의

문제 해결 가이드

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 키의 플랜

지원팀 문의하기