개발자 문서
개발자 문서

환경

같은 주소로 호출하고 X-Env-Scope 헤더 값으로 데모와 정식 중에서 고릅니다.

작업을 제출하고 조회하는 요청에 X-Env-Scope 헤더를 넣습니다. 주소는 환경이 달라도 같고, 헤더 값만 바꿔 실행할 곳을 고릅니다.

MCP 연결은 헤더 이름이 X-MCP-Env-Scope 이고 생략할 수 있습니다(MCP 개요).

헤더 값은 데모(real_test)와 정식(production) 두 가지입니다. 고객 콘솔 상단 전환기도 데모와 정식 두 가지를 보여 줍니다.

환경 비교

데모real_test
연결 대상
실제 기관
체험 제공량
현재 혜택은 요금제에서 확인해 주세요
이용 조건
승인된 조직 — 가입하면 자동 승인, 승인 전이면 콘솔에서 신청
기간
현재 데모 기간 확인 필요 — 승인 후 적용됩니다
MCP 연동
사용 가능 — 같은 한도를 REST 와 나눠 씁니다
정식production
연결 대상
실제 기관
일일 한도
현재 혜택은 요금제에서 확인해 주세요
한 달 한도
현재 혜택은 요금제에서 확인해 주세요 — 구독 결제일 기준으로 다시 채워집니다
이용 조건
요금제를 시작한 뒤
MCP 연동
사용 가능
현재 혜택은 요금제에서 확인해 주세요. 정식 환경은 요금제의 현재 한도를 따릅니다. API별 사용 토큰은 상품 안내와 실행 전 응답에서 확인해 주세요.

키에 환경이 붙는 순서

환경은 요청 헤더로 고르지만, 그 환경을 쓸 수 있는지는 API 키에 붙은 환경 목록이 정합니다.

  • 데모는 조직의 데모가 승인되어 있으면 키에 붙습니다.
  • 정식은 요금제를 시작하면 열립니다. 라이트는 콘솔 결제 관리의 요금제에서 한 번 눌러 시작하고 카드 등록이 없습니다.

자세한 과정은 API 키 발급에 있습니다.

환경 때문에 막힐 때

코드HTTP언제할 일
VALIDATION_ENV_SCOPE_MISMATCH422환경을 보내지 않았거나, 정해진 값이 아닌 값(예: test)을 보냈거나, 두 통로에 서로 다른 값을 담았습니다. 서버는 빠진 환경을 자동으로 채우지 않습니다.X-Env-Scope: real_test 또는 X-Env-Scope: production 을 넣습니다.
POLICY_ENV_FORBIDDEN403키에 없는 환경으로 호출했습니다. 요금제를 시작하지 않으면 production 이, 데모 승인 전에는 real_test 가 키에 없습니다. 데모 기간(현재 데모 기간 확인 필요)이 끝난 뒤 데모로 작업을 제출했을 때도 이 코드이고, 이때는 reason 이 demo_period_ended 입니다. 데모 기간은 작업 제출에만 적용되어 이미 만든 작업의 상태와 결과 조회는 막지 않습니다.키의 환경을 확인하고, 데모는 콘솔에서 신청해 승인을 받습니다. 데모 기간이 끝났다면 요금제를 시작해 정식(production)으로 옮깁니다.
POLICY_PAID_REQUIRED402키에 production 이 있는데 요금제 구독이 정상(ACTIVE) 상태가 아닙니다. 결제 문제로 구독이 일시정지되면 데모도 이 코드로 막힙니다.콘솔 결제 관리에서 플랜 상태를 확인합니다.
POLICY_QUOTA_EXCEEDED429사용 토큰 한도를 넘었습니다. 현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요. 정식 환경은 현재 요금제에 표시된 한도를 따릅니다.하루 한도는 다음 날 0시(KST)에 초기화되고, 한 달 한도는 구독 결제일 기준으로 다시 채워집니다. 그 전에 더 써야 하면 데모는 요금제를 시작해 정식으로 전환하고, 정식은 콘솔 결제 화면에서 요금제를 올립니다.
POLICY_RATE_LIMIT_EXCEEDED429짧은 시간에 너무 많이 호출했습니다(기본 분당 60회).잠시 뒤 다시 호출합니다. 이 오류는 재시도해도 되는 오류입니다.

데모에서 연동 흐름을 끝까지 확인한 다음, 정식으로 옮길 때는 같은 코드에서 X-Env-Scope 값만 production 으로 바꿉니다. 정식은 요금제를 시작한 뒤에 열립니다.