오류 코드

오류가 나면 HTTP 상태 코드와 함께 JSON 을 돌려줍니다. 어느 단계에서 막혔는지에 따라 형식이 조금 다릅니다.

오류 응답 형식

인증 · 권한 단계

토큰과 권한을 먼저 확인하는 단계입니다. 여기서 막히면 API 까지 요청이 가지 않습니다.

{
  "message": "Access token is missing",
  "status": 401,
  "errors": [],
  "code": "G001",
  "timestamp": "2026-10-28T16:07:44.288Z",
  "traceId": "3f9c2a7e-5b1d-4c8a-9e6f-2d7b8a1c4e90"
}

API 처리 단계

요청 값이나 데이터 문제로 실패한 경우입니다.

{
  "message": "searchStartDt 은 UTC(Z) ISO-8601 형식이어야 합니다.",
  "status": 400,
  "errors": [],
  "code": "C001",
  "timestamp": "2026-10-24T03:15:20Z",
  "traceId": "3f9c2a7e-5b1d-4c8a-9e6f-2d7b8a1c4e90"
}

필드	설명
`code`	오류 코드. 아래 표 참고. 분기 처리는 이 값으로 하세요
`message`	사람이 읽는 설명. 문구는 바뀔 수 있습니다
`status`	HTTP 상태 코드와 같은 값
`errors`	파라미터 검증 오류 상세 `{field, value, reason}`. 없으면 `[]`
`timestamp`	오류 발생 시각(UTC). 단계에 따라 초 또는 밀리초까지 표시됩니다
`traceId`	요청 추적 ID. 응답 헤더 `X-Request-Id` 와 같은 값입니다. 문의할 때 함께 알려 주세요

인증 · 권한 오류

code	HTTP	언제	대응
`G001`	401	`Authorization` 헤더가 없음	`Bearer {accessToken}` 추가
`G002`	401	토큰이 올바르지 않음 (형식 오류, 위조, `Bearer` 접두사 누락)	토큰 다시 발급
`G003`	401	토큰 만료 (발급 후 1시간)	토큰 다시 발급
`G004`	401	폐기된 토큰 (secret 재발급·폐기 이후)	새 secret 으로 토큰 발급
`G005`	403	이 API 를 사용할 권한이 없음	모비두 운영팀에 권한 확인 요청
-	429	호출 한도 초과 (본문 없음)	`Retry-After` 초 후 재시도. 호출 제한 참고
`G009`	503	인증 시스템 일시 장애	잠시 후 재시도

게이트웨이 일시 오류

API 서버까지 요청을 전달하는 중에 문제가 생기면 게이트웨이가 직접 응답합니다. 본문 형식은 인증 · 권한 단계 오류와 같습니다.

code	HTTP	언제	대응
`G011`	503	요청이 몰려 처리 대기열이 가득 참	잠시 후 재시도. 반복되면 호출 간격을 늘려 주세요
`G012`	504	API 서버가 60초 안에 응답하지 못함	조회 기간을 줄여 다시 시도. 반복되면 `traceId` 와 함께 문의
`G013`	502	API 서버에 연결하지 못함	잠시 후 재시도. 반복되면 `traceId` 와 함께 문의

API 처리 오류

code	HTTP	언제	대응
`C001`	400	필수 파라미터 누락, 값 형식 오류	`errors`·`message` 확인 후 수정
`C005`	400	허용하지 않는 값 (예: 정해진 값 외의 `broadcastStatus`)	허용 값 확인
`OA001`	400	기간이 KST 자정(또는 정시)에 맞지 않음	기간 규칙 확인
`OA002`	400	조회 기간 31일 초과	기간을 나눠 조회
`U008`	403	경로의 `{partnerId}` 가 토큰의 파트너와 다름	본인 파트너 ID 사용
`C003`	404	`/sauce-live/stats/` 아래의 없는 경로, 또는 `x-api-version` 헤더 누락·불일치	경로·헤더 확인 (`message` 에 필요한 헤더 값 안내)
`B001`	404	해당 파트너에 그 방송이 없음	방송 ID 확인
`C002`	405	GET 이 아닌 메서드	GET 사용
`OA004`	502	연동 시스템이 일시적으로 응답하지 않음	잠시 후 재시도
`C004`	500	서버 오류	traceId 와 함께 문의

📘
토큰이 없거나 틀린 요청은 경로·헤더가 틀려도 인증 오류(401)가 먼저 납니다. 토큰을 고친 뒤에 404 C003 같은 오류가 보일 수 있습니다.
단, /sauce-live/stats/ 로 시작하지 않는 주소는 인증 전에 404 로 응답하며, 본문에 code 와 traceId 가 없습니다. 주소를 다시 확인해 주세요.

토큰 발급 오류

액세스 토큰 발급 API 의 오류입니다.

응답	HTTP	언제
`{"code": "G010", ...}`	400	`x-api-version` 헤더가 없거나 값이 다름
`{"error": "invalid_client"}`	401	`clientId`·`clientSecret` 이 틀렸거나 폐기됨
`{"error": "invalid_request"}`	400	`grant_type` 이 없음
`{"error": "unsupported_grant_type"}`	400	`grant_type` 이 `client_credentials` 가 아님