환경

같은 주소로 호출하고 X-Env-Scope 헤더 값으로 샌드박스·데모·정식을 고릅니다.

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

콘솔에서는 같은 세 환경을 샌드박스 · 데모 · 정식 으로 부릅니다.

환경 비교

샌드박스sandbox

연결 대상: 모의 응답 — 실제 기관을 호출하지 않습니다
일일 한도: 없음
이용 조건: 키를 발급하면 바로
MCP 연동: 사용할 수 없습니다

데모real_test

연결 대상: 실제 기관
일일 한도: 사용자당 100 사용 토큰 — 작업 제출 기준, 매일 0시(KST) 초기화
이용 조건: 승인된 조직 — 가입하면 자동 승인, 승인 전이면 콘솔에서 신청
MCP 연동: 사용 가능 — 같은 한도를 REST 와 나눠 씁니다

정식production

연결 대상: 실제 기관
일일 한도: 없음
이용 조건: 유료 플랜 이용 중
MCP 연동: 사용 가능

키에 환경이 붙는 순서

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

샌드박스는 키를 발급하면 바로 쓸 수 있고, 데모는 조직의 데모가 승인되어 있으면 키에 붙습니다. 가입하면 데모가 자동으로 승인되고, 승인 전이면 콘솔 상단 환경에서 데모 신청을 해 승인받습니다. 신청은 조직의 소유자나 관리자만 할 수 있습니다. 정식은 유료 플랜을 이용하면 열립니다. 자세한 과정은 API 키 발급에 있습니다.

환경 때문에 막힐 때

코드	HTTP	언제	할 일
POLICY_ENV_FORBIDDEN	403	키에 없는 환경으로 호출했거나, 데모 승인 전에 real_test 를 호출했습니다.	키의 환경을 확인하고, 데모는 콘솔에서 신청해 승인을 받습니다.
POLICY_PAID_REQUIRED	402	유료 플랜 이용 중이 아닌데 production 을 호출했습니다. 구독이 정지·해지·만료된 상태에서도 같은 코드가 옵니다.	콘솔 결제 관리에서 플랜 상태를 확인합니다.
POLICY_QUOTA_EXCEEDED	429	데모 일일 한도(사용자당 100 사용 토큰)를 넘었습니다.	다음 날 0시(KST)에 초기화됩니다. 그 전에 더 써야 하면 정식으로 전환합니다.
POLICY_RATE_LIMIT_EXCEEDED	429	짧은 시간에 너무 많이 호출했습니다(기본 분당 60회).	잠시 뒤 다시 호출합니다. 이 오류는 재시도해도 되는 오류입니다.

샌드박스로 연동 흐름을 끝까지 만든 다음, 같은 코드에서 X-Env-Scope 값만 바꿔 데모로 실제 데이터를 확인하는 순서를 권합니다.

MCP 는 샌드박스를 지원하지 않습니다. AI 앱 연결은 데모나 정식에서 시험합니다 — MCP 개요.