Weegloo Docs - 에러

요청이 실패하면 WEEGLOO는 일관된 형식의 오류 본문과 HTTP 상태 코드를 함께 돌려줍니다. 응답 본문의 모양은 어느 API(CMA·CDA·ACMA·ACDA·Upload·Auth)에서 실패했는지와 상관없이 같습니다. 그래서 한 가지 형식만 다룰 줄 알면 모든 오류를 같은 방식으로 분기 처리할 수 있습니다. 이 페이지는 그 공통 형식과 자주 만나는 오류 코드를 한곳에 정리합니다.

오류 응답 형식

오류 본문은 다음과 같은 모양입니다. 아래는 없는 WebHosting을 조회했을 때 받은 응답입니다.

{
  "requestId": "GeR3sEbvWdgvv9eW2NXeanpj2wo6qbkVXgIW7Qd3ea6",
  "sys": {
    "id": "RxcgyPTSuk4GDy6s",
    "type": "NotFound",
    "code": "WGL404001",
    "timestamp": 1781785683556
  },
  "details": {
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } }
  },
  "reason": "WebHosting(...) has been deleted or does not exist.",
  "suggestion": "Please verify WebHosting and try again."
}

각 키의 뜻은 다음과 같습니다.

키	타입	설명
`requestId`	string	이 요청의 추적 식별자. 지원에 문의할 때 이 값을 함께 전달하면 해당 요청을 빠르게 찾을 수 있습니다.
`sys.type`	string	오류 분류. `Unauthorized`·`Forbidden`·`NotFound`·`Unprocessable`·`Conflict`·`TooManyRequest` 등 큰 갈래를 나타냅니다.
`sys.code`	string	세부 오류 코드(예: `WGL409005`). 코드 단위로 분기 처리할 때 이 값을 씁니다.
`sys.timestamp`	integer	오류 발생 시각(epoch millis).
`reason`	string	사람이 읽는 실패 사유.
`suggestion`	string	해결을 돕는 힌트.
`details`	object (선택)	부가 정보. 관련 리소스를 가리키는 `Refer`, 검증 오류 항목 목록(`errors`) 등이 들어갑니다. 오류 종류에 따라 없을 수 있습니다.

분기 처리는 sys.type(큰 갈래)이나 sys.code(세부 코드) 중 필요한 단위로 합니다. 같은 sys.type이라도 sys.code가 다르면 원인이 다르므로, 정확한 처리가 필요하면 sys.code를 기준으로 보세요.

검증에 실패하면 details.errors에 어긋난 항목이 담깁니다. 다음은 본문에 스키마에 없는 속성을 넣어 검증에 실패한 응답입니다.

{
  "requestId": "yJ8KpQ2mWtnLrZ4Xv7BcEadfh3sNuMvKbGT5Pq9wRsx",
  "sys": {
    "id": "Lm2Nq9Tr8KdW4xZc",
    "type": "BadRequest",
    "code": "WGL400006",
    "timestamp": 1781776000000
  },
  "details": {
    "errors": [
      { "path": "", "message": "property 'X' is not defined in the schema", "property": "X" }
    ]
  },
  "reason": "Some values do not satisfy validation rules.",
  "suggestion": "Please check the request body and try again."
}

details.errors의 각 항목은 어긋난 위치(path)와 설명(message), 관련 속성 이름(property)을 담습니다. 항목이 여러 개면 어긋난 값마다 하나씩 들어갑니다.

자주 만나는 코드

다음은 자주 마주치는 오류 코드입니다.

코드	분류	뜻	흔한 상황
`WEB401001`	`Unauthorized`	토큰이 유효하지 않음	`Authorization` Bearer 토큰이 만료됐거나 잘못됐습니다.
`WGL403001`	`Forbidden`	권한 없음	호출자의 역할이 그 작업을 허용하지 않습니다.
`WGL404001`	`NotFound`	리소스가 없거나 삭제됨	잘못된 `sys.id`로 조회했거나, 아직 설정되지 않은 기능을 호출했습니다(예: 커스텀 도메인 미연결).
`WGL400006`	BadRequest	본문 값이 검증 규칙에 어긋남	잘못된 필드 키나 타입으로 본문을 보냈습니다. 어긋난 항목은 `details.errors`에 담깁니다.
`WGL409005`	`Conflict`	리소스가 그새 수정됨	`X-Weegloo-Version` 헤더가 빠졌거나 현재 버전과 다릅니다(규약 참조).
`WGL422007`	`Unprocessable`	발행 상태라 보관할 수 없음	Content나 Media를 보관하려면 먼저 발행취소해야 합니다.
`WGL422009`	`Unprocessable`	발행 상태라 삭제할 수 없음	발행된 Content나 Media를 삭제하려면 먼저 발행취소해야 합니다.
`WGL429001`	`TooManyRequest`	플랜 한도 초과	Organization·Space 등 리소스 생성 개수가 현재 플랜 한도를 넘었습니다. 플랜을 올리면 한도가 늘어납니다.

위 코드는 자주 만나는 일부입니다. 이 밖에도 작업·리소스에 따라 더 많은 코드가 있을 수 있습니다. 어떤 코드를 받든 sys.type으로 큰 갈래를 파악하고, reason·suggestion으로 구체적인 원인과 해결 방향을 확인하세요.

규약: WGL409005를 피하기 위한 X-Weegloo-Version 동시성 규칙.
시스템 속성 (sys): 발행 상태(status)와 WGL422007·WGL422009가 가리키는 라이프사이클.

오류 응답 형식

자주 만나는 코드

관련 문서