개인정보처리방침이 2026년 9월 20일부터 변경됩니다. 온라인 맞춤형 광고 도입에 따라 행태정보 수집·이용 및 국외 이전 관련 조항이 추가됩니다.
개정 내용 보기

문제 해결

실제 에러 메시지별로 원인과 해결 방법을 정리했습니다.

실제 나오는 메시지와 증상을 기준으로 원인을 정리했습니다. 에러 클래스와 처리 방법은 에러 처리를 먼저 보세요.

엔드포인트를 찾을 수 없다고 나옵니다

ApiCookError: 엔드포인트 'air-qualty'를 찾을 수 없습니다. 사용 가능: air-quality, bus-arrival

메시지가 알려주는 목록과 대조하는 것이 가장 빠릅니다. 목록에 있는데도 안 되면 아래 순서로 확인하세요.

  1. 아직 배포하지 않았습니다. 콘솔에서 규칙을 저장한 것과 배포는 다릅니다. 프록시 모드에서는 엔드포인트가 아직 배포되지 않았습니다: {slug}라는 404가 나옵니다.
  2. Free 플랜인데 멀티소스입니다. 소스가 2개 이상인 엔드포인트는 Free에서 설정에 실리지 않습니다. 조용히 빠지기 때문에 "없는 slug"처럼 보입니다.
  3. 원본 API가 자료실에서 삭제됐습니다. 소스 중 하나라도 삭제된 API를 참조하면 엔드포인트 전체가 제외됩니다.
  4. 규칙 버전이 SDK보다 높습니다. 이 경우 콘솔에 경고가 먼저 찍힙니다.
[ApiCook] 엔드포인트 'air-quality'의 규칙 버전(v2)을 지원하지 않습니다. 건너뜁니다.

이 경고가 보이면 SDK를 최신 버전으로 올리세요. 경고를 놓치면 "엔드포인트를 찾을 수 없다"만 남아 원인이 보이지 않습니다.

어제까지 되던 것이 갑자기 404나 503이 됩니다

응답 메시지 원인
503 엔드포인트가 비활성화되었습니다 Pro에서 Free로 내려가면서 한도를 넘은 엔드포인트가 비활성화됨
503 엔드포인트의 원본 API가 삭제되었습니다 자료실에서 원본 API가 내려감
404 엔드포인트를 찾을 수 없습니다 Free 플랜의 멀티소스 제외, 또는 엔드포인트 삭제

키는 맞는데 401이 납니다

ApiCookError: 원본 API 호출 실패 ('air-quality'): 401 Unauthorized

setAuth()에 키를 객체로 감싸지 않은 경우가 1순위입니다.

cook.setAuth('air-quality', 'sk_123');              // ✗ 조용히 무시됩니다
cook.setAuth('air-quality', { serviceKey: 'sk_123' });  // ✓

두 번째 인자에 문자열을 주면 SDK가 그것을 소스 라벨로 해석합니다. 오류가 나지 않고 인증 값만 사라지므로, 원본 API가 키 없이 호출되어 401을 돌려줍니다.

그 밖의 원인:

  • 같은 slug에 setAuth()를 두 번 불러 앞의 키가 교체됐습니다. 병합되지 않습니다.
  • 라벨 전용 설정이 있어 공통 설정이 그 소스에 적용되지 않았습니다.
  • 헤더로 인증하는 API입니다. SDK는 인증 값을 항상 쿼리 파라미터로 보내므로 지원되지 않습니다.

API 키 관련 메시지 구분

메시지 뜻
유효하지 않은 API 키입니다 ApiCook API 키(apk_)가 틀렸습니다. 원본 API 키가 아닙니다
설정 JSON의 서명이 유효하지 않습니다 대개 API 키가 프로젝트와 어긋난 경우입니다. 키를 재발급했다면 코드의 값을 갱신하세요
설정 JSON에 서명이 누락되었습니다 서버가 서명 없는 설정을 보냈습니다. 급하면 verifySignature: false로 우회할 수 있지만 임시 조치입니다

설정 로드 실패

ApiCookError: 설정 로드 실패: 404 Not Found

이것은 원본 API가 아니라 ApiCook 설정 서버 문제입니다. direct 모드에서만 발생합니다.

  • 404 — projectId가 틀렸거나 프로젝트가 삭제됐습니다.
  • 429 — 설정 요청이 너무 잦습니다. cacheTtlMs를 늘리거나 refresh() 호출을 줄이세요.

설정 로드에 실패하면 직전에 받아 둔 설정을 재사용하지 않습니다. 캐시가 만료된 순간부터 모든 호출이 막히므로, 원본 API가 멀쩡한데도 전면 장애처럼 보입니다.

브라우저에서 CORS 오류가 납니다

mode: 'direct'를 직접 지정했을 가능성이 큽니다. 지정을 빼면 브라우저에서 자동으로 proxy 모드가 선택되어 우회됩니다. 자세한 내용은 direct 모드와 proxy 모드에 있습니다.

프록시를 쓰는데도 막힌다면 도메인 제한을 확인하세요.

허용되지 않은 도메인입니다: https://example.com

콘솔의 허용 도메인 목록에 배포 주소를 추가해야 합니다. 참고로 서버에서 호출할 때는 Origin 헤더가 없어 이 검사를 통과합니다.

요청이 너무 많다고 합니다

한도는 두 가지가 따로 걸립니다.

  • IP 기준 분당 60회 — 요청이 너무 많습니다
  • API 키 기준 분당 120회 — 프로젝트 요청 한도를 초과했습니다

응답의 Retry-After 헤더에 대기 시간이 담기지만 SDK는 이를 노출하지 않으므로, 재시도 간격은 직접 정해야 합니다. 월간 사용량 때문에 호출이 막히는 일은 없습니다.

원본 API가 오류를 주는데 이유를 알 수 없습니다

ApiCookError: 원본 API 호출 실패 ('air-quality'): 500 Internal Server Error

SDK는 원본의 응답 본문을 보존하지 않습니다. 공공데이터포털이 SERVICE_KEY_IS_NOT_REGISTERED_ERROR 같은 구체적인 사유를 본문에 담아 보내도 SDK를 통해서는 볼 수 없습니다. 원인을 확인하려면 원본 API를 직접 호출해 보세요.

curl "https://apis.data.go.kr/.../getList?serviceKey=YOUR_KEY&sidoName=서울"

프록시가 502를 돌려줍니다

메시지 원인
지원하지 않는 응답 형식: text/xml 원본이 XML을 반환합니다. 프록시는 JSON만 중계합니다
원본 API가 리다이렉트를 반환했습니다 보안상 리다이렉트를 따라가지 않습니다. baseUrl을 최종 주소로 바꾸세요
응답 크기 초과 (최대 5MB) 파라미터로 결과 수를 줄이세요
내부 네트워크 주소로의 요청은 허용되지 않습니다 baseUrl이 사설 IP나 localhost를 가리킵니다

XML만 제공하는 API는 프록시로 중계할 수 없습니다. direct 모드에서도 JSON 파싱에 실패하므로, JSON 응답 옵션(_type=json, resultType=json 등)이 있는지 원본 문서를 확인하세요.

결과가 null이거나 필드가 비어 있습니다

예외가 나지 않는 실패입니다. 가장 흔하면서 가장 눈에 안 띕니다.

  • 전체가 null → sourceRoot 경로가 원본 응답에 없습니다. 단수·복수(item / items)나 오타를 확인하세요.
  • 특정 필드만 빔 → 그 매핑의 source 경로가 틀렸습니다. 응답에 그 키가 없으면 값이 비고 JSON에서 키째 사라집니다.
  • 배열이어야 하는데 객체 하나만 나옴 → isArray가 꺼져 있습니다.
  • 빈 배열 → 필터 조건이 전부 걸러냈습니다. eq는 타입까지 비교하므로 문자열 "3"과 숫자 3이 다릅니다.

콘솔의 미리보기로 원본 응답과 규칙을 나란히 보면서 맞추는 것이 가장 빠릅니다. 규칙 동작은 가공 규칙 이해하기에 정리돼 있습니다.

호출은 성공하는데 데이터가 계속 비어 있습니다

가공이 전부 실패해도 SDK는 이를 성공으로 집계합니다. 사용량 대시보드가 정상으로 보인다고 해서 데이터가 제대로 오고 있다는 뜻은 아닙니다. 빈 결과를 감지하는 코드를 애플리케이션 쪽에 두세요.

proxy 모드에서 파라미터가 사라집니다

proxy 모드는 설정을 받지 않아서, 파라미터 값 중 하나라도 객체이면 멀티소스 호출로 간주합니다.

// 단일 소스인데 값이 객체라 소스 이름으로 오해받습니다
await cook.fetch('search', { filter: { city: '서울' }, q: 'x' });

proxy 모드에서는 파라미터 값을 전부 문자열로 넘기세요. 중첩 객체는 소스 네임스페이스 용도로만 씁니다.

응답이 오래된 것 같습니다

프록시는 같은 파라미터의 응답을 기본 60초 캐시합니다. 실시간성이 필요하면 콘솔에서 엔드포인트의 캐시 시간을 0으로 두세요. 일부 소스가 실패한 응답은 애초에 캐시되지 않습니다.

설정을 방금 배포했는데 반영되지 않는다면 SDK의 설정 캐시(기본 60초) 때문입니다.

await cook.refresh();

호출이 끝나지 않습니다

direct 모드의 단일 소스 호출에는 제한 시간이 없어 원본이 응답하지 않으면 무한정 기다립니다. 서버에서는 호출부에서 직접 시간을 제한하세요 — 예시는 에러 처리에 있습니다.

타입 에러가 납니다

멀티소스 파라미터나 3인자 setAuth()에서 타입 오류가 난다면 설치된 SDK 버전이 낮은 것입니다. 최신 버전으로 올리고, 그래도 남으면 node_modules를 지우고 다시 설치해 보세요.