API 개요

Base URL

LexQ는 용도에 따라 두 개의 Base URL을 제공합니다:

API	Base URL	용도
Management API	`https://api.lexq.io/api/v1/partners`	정책 생명주기 (생성, 테스트, 배포)
Execution API	`https://api.lexq.io/api/v1/execution`	런타임 정책 평가 (고객 앱에서 호출)

두 Base URL을 혼용하지 마세요. Management 엔드포인트는 Execution Base URL에서 404를 반환하며, 그 반대도 마찬가지입니다.

인증

LexQ는 API Key 인증을 사용합니다. 모든 요청에 키를 포함하세요:

x-api-key: YOUR_API_KEY

API 키는 콘솔의 Management → API Keys에서 생성 및 관리합니다.

API 키는 조직의 정책 엔진에 대한 전체 접근 권한을 부여합니다. 클라이언트 측 코드나 공개 저장소에 노출하지 마세요.

요청 형식

모든 요청 및 응답 본문은 JSON을 사용합니다. Content-Type 헤더를 설정하세요:

Content-Type: application/json

응답 형식

모든 응답은 일관된 엔벨로프를 따릅니다:

{
    "result": "SUCCESS",
    "data": { ... },
    "message": null
}

{
    "result": "ERROR",
    "data": null,
    "code": "P-001",
    "message": "Policy group not found."
}

최상위 필드는 result (값: "SUCCESS" 또는 "ERROR")이며, success: true/false가 아닙니다. 연동 코드에서 항상 result === "SUCCESS"를 확인하세요.

에러 코드

에러 코드는 접두사 규칙을 따릅니다:

접두사	도메인
`C-xxx`	공통 (입력 검증, 조회 실패, 속도 제한)
`A-xxx`	인증 (자격 증명, API 키, 세션)
`P-xxx`	정책 엔진 (그룹, 버전, 규칙, 배포)
`I-xxx`	멱등성
`S-xxx`	시스템 / 암호화
`B-xxx`	결제 (구독, 결제, 할당량)
`M-xxx`	멤버 & 계정
`AN-xxx`	분석 & 시뮬레이션
`ACT-xxx`	액션 검증 (할인, 포인트, 알림)
`FD-xxx`	팩트 정의
`INT-xxx`	연동
`FL-xxx`	장애 로그
`WH-xxx`	웹훅 구독

자세한 내용은 에러 레퍼런스를 참조하세요.

속도 제한

속도 제한은 조직(tenant) 단위로 적용됩니다 — 동일 조직의 모든 API 키가 같은 한도를 공유합니다. 한도는 플랜의 Max TPS 설정에 따라 결정됩니다:

플랜	Max TPS
Free	10
Growth	100
Pro	500
Enterprise	별도 협의

스로틀링은 1초 단위 strict fixed window 방식입니다 — 카운터는 매 epoch 초마다 리셋됩니다. 해당 초 안에서 TPS 한도를 초과한 요청은 HTTP 429 Too Many Requests와 C-007 코드를 받습니다. 실행 엔드포인트의 경우, 배치와 복합 호출은 포함된 팩트 세트 수와 무관하게 TPS에 대해 1건의 요청으로 계산됩니다. 이 점이 플랜을 업그레이드하지 않고 트래픽 스파이크를 처리하는 가장 직접적인 방법입니다.

API 키를 추가 발급해도 실효 TPS는 늘어나지 않습니다 — 모든 키가 동일한 tenant 버킷을 공유합니다. 한도를 올리려면 플랜을 업그레이드하거나, 호출을 배치로 묶어 한 요청 안에 더 많은 작업을 담으세요.

멱등성

실행 엔드포인트에 Idempotency-Key 헤더를 포함하여 중복 처리를 방지할 수 있습니다:

Idempotency-Key: unique-request-id-123

동일한 키로 중복 요청 시 정책을 다시 실행하지 않고 원래 응답을 반환합니다.

페이지네이션

목록 엔드포인트는 페이지네이션된 결과를 반환합니다:

{
  "result": "SUCCESS",
  "data": {
    "content": [ ... ],
    "totalElements": 42,
    "totalPages": 3,
    "pageNo": 0,
    "pageSize": 20
  }
}

pageNo (0부터 시작)와 pageSize 쿼리 파라미터로 페이지를 탐색합니다.

개요

정책 실행

Base URL

인증

요청 형식

응답 형식

에러 코드

속도 제한

멱등성

페이지네이션

다음 단계

인증

정책 실행

​Base URL

​인증

​요청 형식

​응답 형식

​에러 코드

​속도 제한

​멱등성

​페이지네이션

​다음 단계

인증

정책 실행

Base URL

인증

요청 형식

응답 형식

에러 코드

속도 제한

멱등성

페이지네이션

다음 단계