모든 엔드포인트는 application/json을 반환해요. 에러는 RFC 7807 (Problem+JSON)을 따라요. 모든 응답에는 서버 감사 로그와 상관관계를 맺기 위한 X-Request-Id 헤더가 포함돼요.
| Method | Path | 권한 범위 | 용도 |
|---|---|---|---|
| GET | /v1/health | public | 인증 없는 헬스 체크. |
| GET | /v1/me | any | 본인 계정 정보 및 키 메타데이터. |
| GET | /v1/products | read:products | 공개 판매 중인 모든 제품과 가격 목록. |
| GET | /v1/products/{id} | read:products | 제품 상세, 구성 옵션 포함. |
| POST | /v1/orders | write:orders | 주문 처리. Idempotency-Key 필수. |
| GET | /v1/orders/{id} | read:orders | 본인 주문 상태 조회. |
| GET | /v1/services | read:services | 본인 서비스 목록 (페이지네이션 지원). |
| GET | /v1/services/{id} | read:services | 본인 서비스 상세. |
| GET | /v1/services/{id}/credentials | read:credentials | 서비스 자격증명 (별도 권한 범위, 감사 로그 기록). |
| POST | /v1/services/{id}/actions | write:services | 서비스 액션: start, stop, reboot, cancel (결제 기간 종료 시), cancel_revoke. |
| GET | /v1/billing/balance | read:billing | 크레딧 잔액. |
| GET | /v1/billing/invoices | read:billing | 본인 청구서 목록 (페이지네이션 지원). |
| GET | /v1/billing/invoices/{id}/pdf | read:billing | 청구서 PDF. |
| GET | /v1/webhooks | read:webhooks | 현재 웹훅 URL. |
| PUT | /v1/webhooks | write:webhooks | 웹훅 URL 설정 또는 해제. |
멱등성
POST /v1/orders와 POST /v1/services/{id}/actions에는 Idempotency-Key 헤더가 필요합니다([A-Za-z0-9_.-] 문자로 이루어진 1자 이상 80자 이하). 이 키는 메서드, 경로, 본문에 연결됩니다. 1시간 이내에 같은 키로 같은 요청을 반복하면 저장된 응답이 반환됩니다. 그 이후에는 reason replay_stale과 함께 410이 반환되므로 새 키를 전송하십시오. 같은 키를 다른 본문이나 다른 엔드포인트에 사용하면 409 idempotency_conflict로 거부됩니다.
속도 제한
기본적으로 키당 분당 60회(버스트 20회 추가 허용)와 하루 5,000회, 모든 키를 합산한 계정당 분당 120회, 출발지 IP당 분당 600회로 제한됩니다. 제한을 초과하면 Retry-After 헤더와 함께 HTTP 429가 반환됩니다. 응답 헤더 X-RateLimit-Remaining과 X-RateLimit-Reset에서 키 제한의 현재 상태를 확인하실 수 있습니다.
