콘텐츠로 이동

Hive Axyl Server API 오류 처리

앱 서버가 Hive Axyl Server API를 호출하면 HTTP 상태 코드와 응답 본문으로 처리 결과를 받습니다. 응답 본문의 구조는 모든 제품이 같은 규칙을 따르지만, 오류 코드와 오류 응답에 담기는 추가 정보는 제품마다 다릅니다. 이 페이지에서는 모든 제품에 공통인 응답 구조와 오류 확인 순서를 먼저 설명하고, 제품별 응답과 오류 코드를 이어서 설명합니다.

오류 응답 확인 순서

오류 응답을 받으면 아래 순서로 원인을 확인하세요.

  1. 호출한 API의 응답 상태 표에서 HTTP 상태 코드의 의미를 확인하세요.
  2. 응답 본문의 code로 오류 원인을 구분하세요.
  3. type으로 공통 오류인지 제품별 오류인지 확인하세요. /errors/common/으로 시작하면 공통 오류입니다.
  4. 응답 본문에 errors가 있으면 유효성 검사에 실패한 요청 필드를 확인하세요.
  5. 응답 본문에 outcome이 있으면 해당 제품의 설명에 따라 추가 정보를 확인하세요.

같은 HTTP 상태 코드에 여러 code가 올 수 있으므로, 오류 원인은 HTTP 상태 코드가 아니라 code로 구분하세요.

응답 본문 구조

성공 응답과 오류 응답은 콘텐츠 유형과 본문 구조가 다릅니다.

성공 응답

성공 응답의 콘텐츠 유형은 application/json이며, 본문은 data와 meta 두 필드로 이루어집니다.

  • data: API가 반환하는 결과. 반환할 결과가 없는 API는 null을 반환합니다.
  • meta: 결과에 딸린 부가 정보. 페이지 정보처럼 부가 정보가 있는 API만 값을 채우고, 나머지 API는 null을 반환합니다.

각 API가 data와 meta에 담는 필드는 API 레퍼런스의 성공 응답 설명을 참조하세요.

오류 응답

오류 응답의 콘텐츠 유형은 application/problem+json입니다. 본문은 HTTP API의 오류 응답 형식 표준인 RFC 9457 Problem Details를 따르며, Hive Axyl이 정의한 필드가 함께 담깁니다.

  • type: 오류 유형을 식별하는 URI 경로. /errors/common/으로 시작하면 공통 오류이고, /errors/token/, /errors/auth/, /errors/payment/, /errors/push/로 시작하면 해당 제품의 오류입니다.
  • title: 오류 유형의 짧은 제목
  • status: HTTP 상태 코드
  • detail: 이번에 발생한 오류의 상세 설명
  • instance: 오류가 발생한 요청 경로
  • code: 오류 원인을 구분하는 코드
  • errors: 요청 필드의 유효성 검사에 실패했을 때만 포함되는 목록. 각 항목의 field에는 검사에 실패한 필드가, message에는 실패 사유가 담깁니다.
  • outcome: 제품이 오류와 함께 전달하는 추가 정보. 포함 여부와 구조는 제품마다 다르므로 제품별 설명을 참조하세요.

공통 오류 코드

아래 코드는 요청 헤더나 요청 본문의 형식이 올바르지 않을 때 여러 제품에서 같은 의미로 반환됩니다. type은 /errors/common/으로 시작하며, HTTP 상태 코드는 400입니다. 리모트 푸시 전송은 X-App-Id 헤더를 받지 않고 필수 필드 누락도 invalid_parameter로 반환하므로, missing_field와 missing_app_id는 반환하지 않습니다.

코드 발생 조건 처리 방법
missing_field 필수 헤더나 필수 필드 자체가 없습니다. X-App-Id 헤더를 보내지 않은 경우가 여기에 해당합니다. X-App-Id 헤더와 필수 필드를 요청에 넣었는지 확인하세요. errors가 있으면 담긴 필드를 먼저 확인하세요.
missing_app_id X-App-Id 헤더는 보냈지만 값이 비어 있습니다. X-App-Id 헤더에 Hive 콘솔에 등록한 App ID를 넣으세요.
invalid_parameter 요청 본문이나 파라미터가 형식에 맞지 않습니다. 호출한 API의 요청 본문 설명에 맞게 값을 고치세요. errors가 있으면 담긴 필드와 사유를 먼저 확인하세요.

세 코드는 모두 앱 서버의 요청을 고쳐야 해결됩니다. 요청을 고치지 않고 다시 보내면 같은 오류가 반환됩니다.

인증 토큰 응답 및 오류

토큰 발급과 액세스 토큰 유효성 확인에 적용됩니다.

응답 상태

인증 토큰 API가 정의한 오류 응답의 HTTP 상태 코드는 모두 400이며, 오류 원인은 code로 구분합니다.

오류 본문

공통 오류(/errors/common/)의 본문에는 outcome이 없습니다. 인증 토큰 제품 오류(/errors/token/)의 본문에는 outcome이 항상 포함되며, 추가 정보가 없으면 null입니다.

인증 토큰 공통 오류 코드

아래 코드는 인증 토큰 API에서 공통으로 반환됩니다. API마다 달라지는 오류 코드는 각 API의 오류 코드 설명을 참조하세요.

코드 발생 조건 처리 방법
temporarily_unavailable 서버가 일시적으로 요청을 처리하지 못했습니다. 바로 다시 보내지 말고 간격을 두고 같은 요청을 다시 보내세요. 재시도 간격은 앱 서버에서 정합니다.

temporarily_unavailable 외의 오류는 같은 요청을 다시 보내도 결과가 같습니다. 요청이나 설정을 고친 뒤 다시 호출하세요.

계정 및 인증 응답 및 오류

사전 인가 키 발급과 유저네임 비밀번호 변경에 적용됩니다.

응답 상태

계정 및 인증 API가 정의한 오류 응답의 HTTP 상태 코드는 모두 400이며, 오류 원인은 code로 구분합니다. 인증 토큰이 없거나 만료되었거나 위조된 요청은 API에 도달하기 전에 401로 거부되며, 이때는 이 페이지에서 설명하는 오류 본문 형식이 적용되지 않습니다.

오류 본문

공통 오류(/errors/common/)의 본문에는 outcome이 없습니다. 계정 및 인증 제품 오류(/errors/auth/)의 본문에는 outcome이 항상 포함되며, 추가 정보가 없으면 null입니다.

계정 및 인증 공통 오류 코드

아래 코드는 계정 및 인증 API에서 공통으로 반환됩니다. API마다 달라지는 오류 코드는 각 API의 오류 코드 설명을 참조하세요.

코드 발생 조건 처리 방법
app_not_found X-App-Id의 앱 정보를 찾을 수 없습니다. 프로젝트 설정 > App ID에서 App ID를 다시 확인하세요.
terminate_service 프로젝트의 서비스가 종료되었습니다. Hive 콘솔에서 프로젝트의 서비스 운영 상태를 확인하세요.
app_id_mismatch X-App-Id 헤더의 App ID가 인증 토큰의 프로젝트에 속하지 않습니다. 요청에 사용한 App ID와 인증 토큰이 같은 프로젝트에 속하는지 확인하세요.
invalid_gateway_context 인증 토큰으로 확인한 호출자 정보가 없거나 유효하지 않습니다. Authorization 헤더에 유효한 토큰을 넣었는지와 요청 경로를 확인하세요.

결제 응답 및 오류

소모성 상품 영수증 검증, 구독 상품 영수증 검증, 구매 내역 조회에 적용됩니다.

응답 상태

  • 200: 요청 성공
  • 400: 요청 오류 또는 결제 제품 오류. 원인은 code와 outcome으로 구분합니다.
  • 500: 서버 오류. 본문에는 outcome이 없습니다.

오류 본문

400 오류 본문에는 공통 오류 코드와 결제 제품 오류 코드(/errors/payment/)가 모두 올 수 있습니다. 결제 제품 오류의 본문에는 오류 원인을 더 자세히 알려주는 outcome 객체가 항상 포함됩니다.

outcome 필드 타입 설명
code integer 결제 서비스가 정한 결과 코드입니다. HTTP 상태 코드와 관계없는 값입니다.
detailCode integer 보조 코드입니다. 보조 코드가 없으면 null이 아니라 필드 자체가 응답에 포함되지 않습니다.
message string 결과 코드를 식별하는 고정 문구입니다. 사용자에게 보여주는 문구가 아니라 원인을 구분하는 데 사용합니다.

결제 공통 오류 코드

결제 API는 공통 오류 코드 외에 아래 공통 코드도 반환합니다. type은 /errors/common/으로 시작합니다.

  • bad_request: 잘못된 요청
  • unauthorized: 인증 토큰이 없거나 유효하지 않은 경우
  • token_expired: 인증 토큰 만료
  • forbidden: 요청 권한 없음
  • resource_not_found: 요청한 리소스 없음
  • method_not_allowed: 허용되지 않은 요청 방식
  • resource_conflict: 요청과 리소스 상태의 충돌
  • unprocessable_content: 처리할 수 없는 요청 내용
  • rate_limit_exceeded: 허용 한도를 넘은 요청 빈도
  • internal_error: 서버 내부 오류
  • service_unavailable: 서비스 일시 중단

token_expired를 받으면 토큰 발급으로 새 토큰을 받은 뒤 다시 호출하세요.

결제 제품 오류 코드

아래 코드는 여러 결제 API에서 반환됩니다. API마다 달라지는 오류 코드는 각 API의 오류 코드 설명을 참조하세요.

코드 의미 반환하는 API
payment_bad_request 요청을 처리할 수 없습니다. 소모성 상품 영수증 검증, 구독 상품 영수증 검증, 구매 내역 조회
payment_invalid_parameter 요청 파라미터가 유효하지 않습니다. 소모성 상품 영수증 검증, 구독 상품 영수증 검증, 구매 내역 조회
payment_unauthorized 결제 요청 권한이 없습니다. 소모성 상품 영수증 검증, 구독 상품 영수증 검증, 구매 내역 조회
payment_resource_not_found 결제 정보를 찾을 수 없습니다. 소모성 상품 영수증 검증, 구독 상품 영수증 검증
verify_error 마켓에서 영수증을 검증하지 못했습니다. 소모성 상품 영수증 검증, 구독 상품 영수증 검증

영수증 검증 outcome.message 값

영수증 검증 API가 오류를 반환하면 outcome.message로 실패 원인을 더 자세히 구분합니다. 주요 값은 아래와 같습니다.

outcome.message 값 의미 처리 방법
INVALID_RECEIPT 영수증이 올바르지 않습니다. 요청의 axylReceipt가 마켓별로 정해진 값인지 확인하세요.
RECEIPT_VERIFY_FAIL 영수증이 위·변조되어 검증에 실패했습니다. 상품을 지급하지 말고, 앱 클라이언트가 보낸 영수증을 가공하지 않고 그대로 전달했는지 확인하세요.
PRICE_VERIFY_FAIL 소모성 상품 영수증 검증 요청의 price가 서버가 확인한 결제 금액과 다릅니다. Apple과 PG 결제는 기본 설정에서 요청을 거절하고, Google과 Steam 결제는 기록만 남기고 거절하지 않습니다. 상품을 지급하지 말고, 요청에 넣은 금액과 통화를 확인하세요.
PURCHASE_NOT_FOUND 검증할 구매 정보를 찾을 수 없습니다. 요청의 storeTransactionId, orderId, axylReceipt가 같은 구매의 값인지 확인하세요.
INVALID_REQUEST 소모성 상품 영수증 검증에서 Google Play 구매 토큰으로 검증하면서 productId를 보내지 않았습니다. 요청에 productId를 추가하세요.

구매 내역 조회에서만 반환되는 outcome.message 값은 구매 내역 조회의 API별 오류 추가 객체를 참조하세요.

푸시 알림 응답 및 오류

리모트 푸시 전송에 적용됩니다.

응답 상태

상태 의미
202 요청이 접수되었습니다. data와 meta는 모두 null입니다.
400 요청 유효성 검사에 실패했거나 요청이 허용 범위를 벗어났습니다.
500 서버 오류입니다. code는 internal_error이고 본문에 outcome이 없습니다.

오류 본문

공통 오류(/errors/common/)의 본문에는 outcome이 없습니다. 푸시 알림 제품 오류(/errors/push/)의 본문에는 outcome이 항상 포함되며, 추가 정보가 없으면 null입니다.

요청 본문 필드의 타입이 명세와 다르면 본문을 해석하는 단계에서 요청이 실패하므로, invalid_parameter 응답에 errors가 포함되지 않습니다. 예를 들어 숫자여야 하는 targetPlayerId에 문자열을 넣으면 errors 없이 invalid_parameter가 반환됩니다.

푸시 알림 오류 코드

리모트 푸시 전송이 400으로 반환하는 코드입니다. 공통 오류 코드 표의 세 코드 중에서는 invalid_parameter만 반환합니다.

코드 type 발생 조건 처리 방법
invalid_parameter /errors/common/invalid-parameter 요청 본문이 형식에 맞지 않습니다. 공통 오류 코드와 같은 코드입니다. errors가 있으면 담긴 필드와 사유를, 없으면 요청 본문 필드의 타입을 확인하세요.
bad_request /errors/common/bad-request 잘못된 요청입니다. 요청 본문을 리모트 푸시 전송의 설명과 비교해 확인하세요.
resource_not_in_scope /errors/push/resource-not-in-scope 요청 본문의 appIds에 인증 토큰의 프로젝트에 속하지 않는 App ID가 있습니다. 프로젝트 설정 > App ID에서 같은 프로젝트의 App ID만 지정했는지 확인하세요.
invalid_subject /errors/push/invalid-subject 이 API가 허용하지 않는 토큰으로 호출했습니다. 사용자의 로그인 토큰으로 호출한 경우가 여기에 해당합니다. 토큰 발급으로 받은 앱 서버용 토큰으로 호출하세요.