오류 | 설명서 - Roblox 크리에이터 허브

다음 섹션에서는 Open Cloud API의 오류 처리에 대해 설명합니다. 엔드포인트와 검증 레이어 간의 구현 차이로 인해 오류 응답의 형식은 크게 다를 수 있습니다.

게이트웨이 오류

인증 또는 라우팅 문제가 발생할 경우 Open Cloud v1 및 v2 API는 다음 형식으로 오류를 반환할 수 있습니다:

예제 게이트웨이 오류
{
  "errors": [
    {
      "code": 0,
      "message": "유효하지 않은 API 키"
    }
  ]
}

Open Cloud v2

Open Cloud v2 API는 오류가 API 엔드포인트 자체 내에서 발생할 때 일반적으로 일관된 오류 형식을 따릅니다.

표준 v2 오류 형식

Open Cloud v2 API는 다음 형식으로 오류를 반환합니다:

code - 오류 유형을 나타내는 문자열 (예: INVALID_ARGUMENT, NOT_FOUND).
message - 오류를 설명하는 인간이 읽을 수 있는 메시지.
details - 추가 오류-specific 정보를 포함하는 선택적 배열입니다.

예제 v2 오류
{
  "code": "INVALID_ARGUMENT",
  "message": "요청에서 유효하지 않은 사용자 ID."
}

상세 정보가 포함된 예제 v2 오류
{
  "code": "INVALID_ARGUMENT",
  "message": "제공된 필터가 유효하지 않습니다.",
  "details": [
    {
      ...
    }
  ]
}

v2 오류 코드

다음 표는 v2 API 응답에서 code의 가능한 값을 설명합니다.

코드	HTTP 상태	설명
INVALID_ARGUMENT	400	유효하지 않은 인수를 전달했습니다. (예: 유효하지 않은 universeId). Content-Length 및 Content-Type과 같은 유효하지 않거나 누락된 헤더가 있을 수 있습니다.
PERMISSION_DENIED	403	작업을 수행하기에 충분한 권한이나 범위가 없습니다.
NOT_FOUND	404	시스템에서 지정한 리소스를 찾을 수 없습니다. (예: 데이터 저장소 항목).
ABORTED	409	작업이 중단되었습니다.
RESOURCE_EXHAUSTED	429	작업을 수행하기 위한 충분한 할당량이 없습니다. 일반적으로 너무 많은 요청을 보내서 발생합니다.
CANCELLED	499	시스템이 요청을 종료합니다. 일반적으로 클라이언트 측의 시간 초과로 인해 발생합니다.
INTERNAL	500	내부 서버 오류, 일반적으로 서버 버그 때문입니다.
NOT_IMPLEMENTED	501	서버가 API 메서드를 구현하지 않았습니다.
UNAVAILABLE	503	서비스를 사용할 수 없습니다. 일반적으로 서버가 다운된 경우에 반환됩니다.

Open Cloud v1

Open Cloud v1 API는 일관되지 않은 오류 응답 형식을 가지고 있습니다. 형식은 특정 엔드포인트, 오류 유형, 요청 처리 파이프라인 내에서 오류가 발생하는 위치에 따라 다릅니다.

대부분의 v1 엔드포인트는 다음 세 가지 형식 중 하나로 오류를 반환합니다:

오류 필드가 있는 예제 v1 오류
{
  "error": "INVALID_ARGUMENT",
  "message": "유효하지 않은 커서입니다.",
  "errorDetails": [
    {
      "errorDetailType": "DatastoreErrorInfo",
      "datastoreErrorCode": "InvalidCursor"
    }
  ]
}

코드 필드가 있는 예제 v1 오류
{
  "code": "INVALID_ARGUMENT",
  "message": "유효하지 않은 커서입니다."
}

자세한 검증 오류 예제 v1
{
  "errors": {
    "assetId": ["값 'a'는 유효하지 않습니다."]
  },
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "하나 이상의 검증 오류가 발생했습니다.",
  "status": 400,
  "extensions": {
    "traceId": "00-427917f0fc3b8375ee33e4603a7f0693-f3f6ad560ff1a122-00"
  }
}

v1 오류 코드

다음 표는 v1 API 응답에서 error 또는 code의 가능한 값을 설명합니다:

HTTP 상태 코드	오류	설명
400	INVALID_ARGUMENT	유효하지 않은 인수를 전달했습니다. (예: 유효하지 않은 universeId) Content-Length 및 Content-Type과 같은 유효하지 않거나 누락된 헤더가 있을 수 있습니다.
403	INSUFFICIENT_SCOPE	요청은 액세스 토큰으로 제공된 것보다 높은 권한을 요구합니다.
403	PERMISSION_DENIED	작업을 수행하기에 충분한 범위가 없습니다.
404	NOT_FOUND	시스템이 지정한 리소스를 찾을 수 없습니다. (예: 데이터 저장소).
409	ABORTED	물리적 충돌로 인해 작업이 중단되었습니다. (예: 우주에 속하지 않는 장소 게시).
429	RESOURCE_EXHAUSTED	작업을 수행하기 위한 충분한 할당량이 없습니다. 일반적으로 너무 많은 요청을 보내서 발생합니다.
499	CANCELLED	시스템이 요청을 종료합니다. 일반적으로 클라이언트 측의 시간 초과로 인해 발생합니다.
500	INTERNAL	내부 서버 오류. 일반적으로 서버 버그로 발생합니다.
501	NOT_IMPLEMENTED	서버가 API 메서드를 구현하지 않았습니다.
503	UNAVAILABLE	서비스를 사용할 수 없습니다. 일반적으로 서버가 다운되었을 때 발생합니다.