에러 코드

오류 응답 형식

오류 발생 시 다음과 같은 JSON 형식으로 응답합니다.

음성 API

json

{
  "error": {
    "code": "E4001",
    "message": "API key is required. Provide X-API-Key header.",
    "details": "optional additional info"
  }
}

AICC API

AICC는 기존 클라이언트 호환을 위해 같은 공통 코드를 평면 형식으로 반환합니다.

json

{
  "error": "message or a user message in history is required",
  "code": "E4201"
}

규칙

모든 공개 API는 같은 규칙으로 오류를 반환합니다.

상황을 설명하는 실패 분류를 고릅니다. 분류가 코드를 정하고, 코드가 HTTP 상태와 기본 메시지를 정합니다.
메시지는 짧은 영어 문장이며 내부 시스템 정보를 담지 않습니다. 엔드포인트별 맥락은 details(음성 API) 또는 메시지(AICC)에 담습니다.
음성 API는 중첩 객체를, AICC API는 평면 객체를 반환합니다. 두 형식 모두 같은 코드 값을 사용합니다.
재시도할 수 있는 상황(의존 서비스 불가, 과부하, 재시작 중, 사용할 수 없는 결과 반환)은 E5002, 엔드포인트 자체의 제한 시간 초과는 E5003, 그 밖의 예상치 못한 오류는 E5001입니다.

상황별 오류 코드

서버는 상황에 맞는 실패 분류를 하나 고르고, 분류마다 정해진 코드 하나를 반환합니다.

상황별 오류 코드
분류	코드	사용하는 경우	예시
API 키 누락 `api_key_missing`	`E4001`401	API 키가 필요한 엔드포인트를 키 헤더 없이 호출했습니다.	No X-API-Key header on /v1/agents/chat
유효하지 않은 API 키 `api_key_invalid`	`E4002`401	알 수 없거나, 폐기·만료되었거나, 다른 조직의 키입니다.	Revoked key · Key of a different organization
권한 없음 `permission_denied`	`E4101`403	인증은 되었지만 이 기능이나 리소스를 사용할 수 없습니다(요금제 제한, 기능 사용 여부, 소유권).	Plan does not include the feature · Resource owned by another organization
잘못된 요청 `invalid_request`	`E4201`400	보낸 그대로는 처리할 수 없는 요청입니다: 잘못된 JSON, 빠졌거나 유효하지 않은 필드, 서로 맞지 않는 식별자, 알 수 없는 enum 값.	invalid JSON body · turn_id and turnId must match · message is required
텍스트 길이 초과 `text_too_long`	`E4202`400	텍스트 필드가 엔드포인트의 글자 수 한도를 넘었습니다.	TTS text over the per-request limit
유효하지 않은 오디오 `invalid_audio`	`E4203`400	오디오 입력의 형식, 샘플레이트, 크기 또는 길이를 지원하지 않습니다.	Reference audio longer than allowed · Unsupported codec
요청 크기 초과 `payload_too_large`	`E4204`413	요청 body나 구조화된 필드가 엔드포인트의 바이트 한도를 넘었습니다.	Body over the limit · state is too large
리소스 없음 `resource_not_found`	`E4301`404	에이전트, 목소리, 단어장, 작업 또는 경로가 없거나 호출자에게 보이지 않습니다.	Agent not found · HTTP route not found
리소스 준비 전 `resource_not_ready`	`E4302`409	리소스는 있지만 아직 이 요청을 처리할 수 없습니다: 게시 버전이 없거나, 처리 중이거나, 아직 등록되지 않았습니다.	Agent has no published version · Voice still processing
사용량 한도 초과 `usage_limit_exceeded`	`E4401`429	조직의 요금제 사용량 한도에 도달했습니다.	Monthly character quota exhausted
게스트 한도 초과 `guest_limit_exceeded`	`E4402`429	게스트(로그인하지 않은 체험) 일일 한도에 도달했습니다.	Guest demo sessions per day
호출 제한 초과 `rate_limit_exceeded`	`E4403`429	제한 시간 안에 요청 수나 글자 수가 너무 많습니다.	Too many requests per minute
허용되지 않은 메서드 `method_not_allowed`	`E4501`405	경로는 있지만 이 HTTP 메서드는 지원하지 않습니다.	GET on a POST-only route
크레딧 부족 `insufficient_credits`	`E4601`402	조직이 이 요청에 필요한 크레딧을 예약할 수 없습니다.	AICC credits are insufficient
일시적 서비스 불가 `service_unavailable`	`E5002`503	의존 서비스를 사용할 수 없거나, 과부하·재시작 중이거나, 설정이 잘못되었거나, 사용할 수 없는 응답을 반환했습니다. 클라이언트는 재시도할 수 있습니다.	Speech or language model service unavailable or overloaded · Dependent service returned an unusable result · Agent runtime configuration cannot be loaded · Service restarting
처리 시간 초과 `processing_timeout`	`E5003`500	엔드포인트 자체의 제한 시간이 작업 완료 전에 지났습니다.	Synthesis exceeded 150 seconds · Turn deadline exceeded
내부 오류 `internal_error`	`E5001`500	다른 분류에 해당하지 않는 예상치 못한 서버 오류입니다. 내부 정보는 노출하지 않습니다.	Unhandled error · Invariant violated

AICC 런타임 대응 예시

AICC 엔드포인트도 같은 실패 분류를 따르며, 자주 만나는 상황에는 다음 코드로 응답합니다.

AICC 런타임 대응 예시
상황	코드	HTTP
입력값이 잘못됨(빈 메시지, 잘못된 JSON 등)	`E4201`	400
에이전트에 게시 버전이 없음	`E4302`	409
답변 생성에 필요한 서비스를 일시적으로 사용할 수 없음	`E5002`	503
턴 처리 제한 시간을 넘김	`E5003`	500

에러 코드 목록

인증 (Authentication)

코드	HTTP	설명
`E4001`	401	API 키가 필요합니다. X-API-Key 헤더를 제공하세요.
`E4002`	401	유효하지 않은 API 키

권한 (Authorization)

코드	HTTP	설명
`E4101`	403	권한이 없습니다

입력 검증 (Validation)

코드	HTTP	설명
`E4201`	400	잘못된 요청입니다
`E4202`	400	텍스트가 최대 길이를 초과했습니다
`E4203`	400	유효하지 않은 오디오
`E4204`	413	요청 body가 허용 크기를 초과했습니다

리소스 (Resource)

코드	HTTP	설명
`E4301`	404	리소스를 찾을 수 없습니다
`E4302`	409	리소스가 준비되지 않았습니다

사용량 제한 (Rate Limit)

코드	HTTP	설명
`E4401`	429	사용량 한도를 초과했습니다
`E4402`	429	게스트 일일 한도를 초과했습니다
`E4403`	429	분당 요청 또는 글자 수 한도를 초과했습니다

메서드 (Method)

코드	HTTP	설명
`E4501`	405	허용되지 않은 메서드입니다

결제 및 크레딧 (Billing)

코드	HTTP	설명
`E4601`	402	요청을 처리할 크레딧이 부족합니다

서버 (Server)

코드	HTTP	설명
`E5001`	500	내부 서버 오류
`E5002`	503	일시적으로 서비스를 사용할 수 없습니다
`E5003`	500	처리 시간이 초과되었습니다