에러

에러 코드 25종

메시지 자체가 조치 안내입니다. 무엇이 잘못됐는지가 아니라 무엇을 하면 되는지를 적습니다 — AI 코딩 도구가 읽고 스스로 고칠 수 있도록.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "요청 바디의 파라미터가 잘못되었습니다. error.details.issues 에서 어긋난 필드와 사유를 확인하세요.",
    "details": {
      "issues": [
        {
          "field": "birthMonth",
          "message": "1 이상이어야 합니다"
        }
      ]
    },
    "hint": {}
  }
}

400

코드	언제 나나
`BATCH_TOO_MANY_ITEMS`	배치 항목 수가 플랜 상한을 넘을 때. 요청 전체가 거절되며 error.details.maxItems 에 그 키의 상한이 담긴다.
`INVALID_DATE`	평년 2월 30일처럼 존재하지 않는 날짜. 없는 윤달은 LEAP_MONTH_NOT_FOUND 로 따로 안내한다.
`INVALID_JSON`	바디가 JSON 으로 파싱되지 않을 때.
`INVALID_LOCATION`	경도만·시간대만 왔거나 셋 다 없을 때. 경도로 시간대를 추측하지 않는다 — 국경과 역사적 전환에서 틀린다. 섞어 보낸 입력의 `birthCity` 를 못 찾은 경우도 여기다(빠진 값을 서울로 채우지 않는다).
`LEAP_MONTH_NOT_FOUND`	윤달이 없는 해·달에 isLeapMonth 를 켰을 때.
`OUT_OF_SUPPORTED_ERA`	역법 데이터가 덮지 않는 연도.
`SAMPLE_PROFILE_REQUIRED`	Free 키로 핵심 모듈이 유료인 토픽을 샘플 외 생년월일로 부를 때. 코드 오류가 아니라 Free 플랜의 정상 동작이다. error.details 에 부족한 모듈·샘플 목록 주소·가장 가까운 샘플이, error.hint.freeTopics 에 임의의 생년월일로 쓸 수 있는 토픽이 담긴다.
`UNSUPPORTED_CITY`	`birthCity` 를 도시 목록에서 찾지 못했을 때. 전에는 서울로 대신 계산하고 경고만 냈는데, 그러면 다른 사람의 사주가 성공 응답으로 나간다 — 부르는 쪽이 `timezone.cityResolved` 를 검사한다는 것을 알아야만 안전했다. 이제 거절한다.
`UNSUPPORTED_TIMEZONE`	`birthTimezone` 이 번들된 IANA 존 목록에 없을 때. 런타임마다 아는 존이 다르다 — Node 의 Intl 은 417개, 우리는 418개를 안다. 부르는 쪽이 자기 런타임으로 검증해 통과시킨 이름이 우리에게 없을 수 있으므로, 목록의 권위는 이 API 가 갖는다(소비자 서비스 요청). 대소문자를 구분한다.
`VALIDATION_ERROR`	필수 필드 누락·타입 오류·범위 초과. error.details.issues 에 어긋난 필드와 사유가 담긴다. JavaScript Date.getMonth() 의 0~11 을 birthMonth 로 그대로 보내면 여기서 걸린다.

401

코드	언제 나나
`INVALID_API_KEY`	등록되지 않은 키. 발급 후 복사 과정에서 잘리거나 공백이 섞인 경우가 가장 흔하다. 없는 키로 반복 호출하면 IP 단위 제한이 걸린다.
`KEY_EXPIRED`	만료일이 지난 키. Free 키는 발급 후 90일이다.
`KEY_REVOKED`	대시보드에서 폐기한 키. 폐기는 다음 요청부터 즉시 반영된다.
`MISSING_API_KEY`	두 인증 헤더가 모두 없을 때. 헤더 이름의 대소문자는 무관하지만 철자는 정확해야 한다.
`SUBSCRIPTION_REQUIRED`	유료 키인데 유효한 이용권이 없을 때. 기간권은 자동 갱신되지 않으므로 기간이 끝나면 여기로 온다.

402

코드	언제 나나
`QUOTA_EXHAUSTED`	월 포함 건수를 다 썼을 때.

403

코드	언제 나나
`ORIGIN_NOT_ALLOWED`	유료 키에 허용 도메인이 등록돼 있는데 요청 Origin 이 그 목록에 없을 때. Origin 헤더가 없는 서버 사이드 호출은 항상 통과한다.
`PRO_ONLY`	허용 도메인 등록·배치처럼 유료 전용 기능을 Free 키로 쓸 때. 서버 사이드 호출은 도메인 등록 없이 통과한다.

404

코드	언제 나나
`NOT_FOUND`	카탈로그에 없는 경로이거나 HTTP 메서드가 다를 때. 리딩은 전부 POST 이고 카탈로그 조회는 GET 이다.
`TOPIC_NOT_AVAILABLE`	카탈로그에는 있으나 아직 열리지 않은 토픽. error.hint.availableTopics 에 지금 쓸 수 있는 토픽이 담긴다.
`WRONG_ENDPOINT`	흔한 오타를 감지했을 때. error.hint.correctedPath 에 올바른 경로가 담기므로 그대로 바꿔 부르면 된다.

429

코드	언제 나나
`DAILY_BURN_LIMIT`	하루에 월 포함량의 일정 비율을 넘겨 쓸 때. 재시도 루프 버그로 월 한도가 한꺼번에 소진되는 것을 막는 장치다.
`RATE_LIMIT_EXCEEDED`	분당 한도 초과. 잔여량은 매 응답의 X-RateLimit-Remaining 에 담기므로 미리 알 수 있다.

500

코드	언제 나나
`INTERNAL_ERROR`	처리되지 않은 예외. 내부 사정(스택·경로)은 응답에 담지 않는다.

503

코드	언제 나나
`AUTH_UNAVAILABLE`	키를 확인할 수 없을 때. 인증은 통과시키지 않는다 — 확인 못 한 키를 받아들이면 저장소 장애가 곧 인증 우회가 된다.

이 표는 런타임이 쓰는 카탈로그에서 생성됩니다. 코드가 내보내는 에러와 문서가 어긋날 수 없습니다.