오류 처리와 운영
HTTP 오류와 항목 결과를 구분하기#
| 상황 | 대응 |
|---|---|
| 네트워크 / timeout / HTTP 5xx | 같은 key·id로 재시도 |
| HTTP 401 / 403 | 키, 앱 상태와 환경 설정을 확인. 대기열을 보존하고 경고 |
| HTTP 408 / 429 | 대기 후 재시도. 429 응답의 retryAfterSec가 있으면 참고 |
| 그 외 HTTP 4xx | 요청 수정 필요. 실패 원본 보존 후 해당 전송 중단 |
| HTTP 200 + rejected | 항목 reason별 분기. 성공으로 처리하지 않음 |
| HTTP 200 + duplicate | 이미 처리됨. 추가 지급 없이 완료 처리 |
OAuth 오류는 error, error_description 형식입니다. invalid_client는 인증 정보, invalid_grant는 만료·중복 코드, redirect_uri 또는 PKCE 불일치, invalid_token은 토큰 검증 실패를 확인합니다. access_denied는 사용자의 취소입니다.
영속 대기열(outbox)#
- 게임의 판 종료·보상 확정 트랜잭션에 전송 이벤트를 함께 저장합니다.
- 작업기가 최대 100건씩 묶어 API로 보냅니다.
- 응답을 항목별로 저장하고 성공한 이벤트만 완료 처리합니다.
- 응답을 받기 전에 연결이 끊겨도 같은 key·id로 재전송합니다.
- 재시도 소진 이벤트는 별도 보관하고 운영자가 재처리합니다.
키트 권장 간격은 1·5·30·120·360·720분입니다. 지터를 추가하고 401·403에 과도한 재시도를 하지 마세요. PlayusRejected는 일부 영구 HTTP 4xx를 구분하며, HTTP 200 안의 rejected는 호출자가 처리해야 합니다. 키트 자체는 DB 대기열을 제공하지 않습니다.
요청 상한#
Publisher API는 앱당 기본 분당 1,200회입니다(운영 설정으로 변경 가능). 인스턴스별 제한이므로 전역 보장치로 간주하지 마세요. 묶음 전송과 지수 지연을 사용하세요. User-Agent가 비어 있으면 방화벽 정책에 걸릴 수 있습니다.
비밀 키 교체#
운영자가 새 키를 발급하면 원문은 한 번만 표시됩니다. 기존 키는 기본 60분 동안 추가 허용됩니다. 새 키를 서버에 반영하고 재배포한 뒤 ping과 실제 연동을 확인합니다. 비밀 키를 티켓·브라우저 로그·문서에 붙이지 마세요.
문제 진단#
| 증상 | 확인할 곳 |
|---|---|
| iframe이 열리지 않음 | 게임 frame-ancestors, X-Frame-Options, PLAYUS frame-src |
| launch code timeout | ready 메시지, 허용 playus_host, 부모 창 origin/source |
| invalid_grant | 코드 120초 만료, 중복 사용, callback/launchUrl 정확한 일치, verifier |
| 보상은 200인데 잔액이 다름 | 항목 status, held, capped, grantedMb |
| unknown_sub | 다른 앱의 sub, 연결 해제 여부, 환경 혼용 |
로그에는 내부 추적 ID, 이벤트 key, HTTP 상태와 항목 결과만 남기고 client_secret·인가 코드·토큰은 마스킹합니다.