환경
같은 주소로 호출하고 X-Env-Scope 헤더 값으로 데모와 정식 중에서 고릅니다.
작업을 제출하고 조회하는 요청에 X-Env-Scope 헤더를 넣습니다. 주소는 환경이 달라도 같고, 헤더 값만 바꿔 실행할 곳을 고릅니다.
MCP 연결은 헤더 이름이 X-MCP-Env-Scope 이고 생략할 수 있습니다(MCP 개요).
헤더 값은 데모(real_test)와 정식(production) 두 가지입니다. 고객 콘솔 상단 전환기도 데모와 정식 두 가지를 보여 줍니다.
환경 비교
데모real_test
- 연결 대상
- 실제 기관
- 체험 제공량
- 현재 혜택은 요금제에서 확인해 주세요
- 이용 조건
- 승인된 조직 — 가입하면 자동 승인, 승인 전이면 콘솔에서 신청
- 기간
- 현재 데모 기간 확인 필요 — 승인 후 적용됩니다
- MCP 연동
- 사용 가능 — 같은 한도를 REST 와 나눠 씁니다
정식production
- 연결 대상
- 실제 기관
- 일일 한도
- 현재 혜택은 요금제에서 확인해 주세요
- 한 달 한도
- 현재 혜택은 요금제에서 확인해 주세요 — 구독 결제일 기준으로 다시 채워집니다
- 이용 조건
- 요금제를 시작한 뒤
- MCP 연동
- 사용 가능
키에 환경이 붙는 순서
환경은 요청 헤더로 고르지만, 그 환경을 쓸 수 있는지는 API 키에 붙은 환경 목록이 정합니다.
- 데모는 조직의 데모가 승인되어 있으면 키에 붙습니다.가입하면 자동으로 승인되고, 승인 전이면 콘솔 상단 환경에서 데모 신청을 해 승인받습니다. 신청은 조직의 소유자나 관리자만 할 수 있습니다.
- 정식은 요금제를 시작하면 열립니다. 라이트는 콘솔 결제 관리의 요금제에서 한 번 눌러 시작하고 카드 등록이 없습니다.
자세한 과정은 API 키 발급에 있습니다.
환경 때문에 막힐 때
| 코드 | HTTP | 언제 | 할 일 |
|---|---|---|---|
| VALIDATION_ENV_SCOPE_MISMATCH | 422 | 환경을 보내지 않았거나, 정해진 값이 아닌 값(예: test)을 보냈거나, 두 통로에 서로 다른 값을 담았습니다. 서버는 빠진 환경을 자동으로 채우지 않습니다. | X-Env-Scope: real_test 또는 X-Env-Scope: production 을 넣습니다. |
| POLICY_ENV_FORBIDDEN | 403 | 키에 없는 환경으로 호출했습니다. 요금제를 시작하지 않으면 production 이, 데모 승인 전에는 real_test 가 키에 없습니다. 데모 기간(현재 데모 기간 확인 필요)이 끝난 뒤 데모로 작업을 제출했을 때도 이 코드이고, 이때는 reason 이 demo_period_ended 입니다. 데모 기간은 작업 제출에만 적용되어 이미 만든 작업의 상태와 결과 조회는 막지 않습니다. | 키의 환경을 확인하고, 데모는 콘솔에서 신청해 승인을 받습니다. 데모 기간이 끝났다면 요금제를 시작해 정식(production)으로 옮깁니다. |
| POLICY_PAID_REQUIRED | 402 | 키에 production 이 있는데 요금제 구독이 정상(ACTIVE) 상태가 아닙니다. 결제 문제로 구독이 일시정지되면 데모도 이 코드로 막힙니다. | 콘솔 결제 관리에서 플랜 상태를 확인합니다. |
| POLICY_QUOTA_EXCEEDED | 429 | 사용 토큰 한도를 넘었습니다. 현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요. 정식 환경은 현재 요금제에 표시된 한도를 따릅니다. | 하루 한도는 다음 날 0시(KST)에 초기화되고, 한 달 한도는 구독 결제일 기준으로 다시 채워집니다. 그 전에 더 써야 하면 데모는 요금제를 시작해 정식으로 전환하고, 정식은 콘솔 결제 화면에서 요금제를 올립니다. |
| POLICY_RATE_LIMIT_EXCEEDED | 429 | 짧은 시간에 너무 많이 호출했습니다(기본 분당 60회). | 잠시 뒤 다시 호출합니다. 이 오류는 재시도해도 되는 오류입니다. |
데모에서 연동 흐름을 끝까지 확인한 다음, 정식으로 옮길 때는 같은 코드에서 X-Env-Scope 값만 production 으로 바꿉니다. 정식은 요금제를 시작한 뒤에 열립니다.