문서

S2S API 응답 코드 및 오류 처리

Singular의 S2S API 응답 코드를 이해하고 적절한 오류 처리를 구현하면 안정적인 데이터 전송 및 어트리뷰션 정확도와 함께 강력한 연동을 보장할 수 있습니다.

응답 아키텍처

HTTP 상태 코드 동작

핵심 이해: Singular의 API와 연동할 때, 모든 응답은 HTTP 200 상태 코드를 반환하므로 응답 본문의 '상태' 필드의 유효성을 검사하여 성공('ok') 또는 실패('error')를 확인해야 합니다.

응답 페이로드에는 상태가'오류'인 경우 자세한 오류 정보를 제공하는'이유' 필드가 포함됩니다.

응답 구조: 모든 API 응답은 성공 또는 실패에 관계없이 일관된 JSON 형식을 따르므로 모든 엔드포인트 상호 작용에서 표준화된 구문 분석 및 오류 처리가 가능합니다.

오류 처리 전략

구현 모범 사례

포괄적인 오류 처리 전략을 구현하여 데이터 무결성과 시스템 안정성을 보장하세요.

권장 접근 방식:

재시도 메커니즘: 구성 가능한 최대 시도를 통해 지수적 백오프 재시도를 구현하세요.
순차적 처리: 재시도 중 요청 순서를 유지하여 데이터 일관성 보장
오류 분류: 재시도 가능한 오류와 재시도 불가능한 오류를 구분(유효하지 않은 매개변수는 재시도하지 않아야 함)
포괄적인 로깅: 원본 매개변수, 오류 메시지, 장치 식별자, 타임스탬프를 포함한 모든 실패한 요청을 기록합니다.
모니터링 및 알림: 재시도 시도를 추적하고 중대한 실패에 대한 알림 시스템을 구현합니다.

지수 백오프 구현

지수 백오프는 일시적인 장애 발생 시 서버 과부하를 방지하는 동시에 효율적인 재시도 전략을 제공합니다.

재시도 전략:

초기 지연: 첫 번째 실패 후 1~2초 지연으로 시작
백오프 승수: 이후 재시도할 때마다 지연 시간 2배 증가(2초 → 4초 → 8초 → 16초)
최대 시도 횟수: 제한 구성(권장: 3~5회 시도)
최대 지연: 적절한 임계값(예: 60초)에서 지연을 제한합니다.
지터: 무작위 지터를 추가하여 천둥 번개 효과를 방지합니다.

import requests
import time
import random

def exponential_backoff_request(url, params, max_retries=3):
    """
    Make API request with exponential backoff retry logic
    """
    base_delay = 1  # Start with 1 second
    max_delay = 60  # Cap at 60 seconds
    
    for attempt in range(max_retries):
        try:
            response = requests.get(url, params=params, timeout=10)
            
            # All responses return HTTP 200
            if response.status_code == 200:
                data = response.json()
                
                if data.get('status') == 'ok':
                    return {'success': True, 'data': data}
                    
                # Check if error is retryable
                reason = data.get('reason', '')
                if is_retryable_error(reason):
                    if attempt

import java.net.http.*;
import java.time.Duration;
import java.util.*;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

public class SingularAPIClient {
    private static final int MAX_RETRIES = 3;
    private static final long BASE_DELAY_MS = 1000;
    private static final long MAX_DELAY_MS = 60000;
    private static final HttpClient client = HttpClient.newHttpClient();
    
    public static ApiResponse exponentialBackoffRequest(String url, Map params) {
        for (int attempt = 0; attempt  response = client.send(request, 
                    HttpResponse.BodyHandlers.ofString());
                
                // Parse JSON response
                JsonObject jsonResponse = JsonParser.parseString(response.body())
                    .getAsJsonObject();
                String status = jsonResponse.get("status").getAsString();
                
                if ("ok".equals(status)) {
                    return new ApiResponse(true, jsonResponse.toString(), false);
                }
                
                // Handle error response
                String reason = jsonResponse.has("reason") 
                    ? jsonResponse.get("reason").getAsString() 
                    : "Unknown error";
                
                if (!isRetryableError(reason)) {
                    return new ApiResponse(false, reason, false);
                }
                
                // Retry with exponential backoff
                if (attempt <><> params) {
        // Implementation of URL parameter building
        StringBuilder url = new StringBuilder(baseUrl).append("?");
        params.forEach((key, value) - 
            url.append(key).append("=").append(URLEncoder.encode(value)).append("&")
        );
        return url.toString();
    }
}

class ApiResponse {
    public final boolean success;
    public final String message;
    public final boolean retryable;
    
    public ApiResponse(boolean success, String message, boolean retryable) {
        this.success = success;
        this.message = message;
        this.retryable = retryable;
    }
}

로깅 및 모니터링

포괄적인 로깅을 통해 신속한 문제 해결이 가능하며 연동 상태에 대한 가시성을 제공합니다.

필수 정보를 로깅하세요:

요청 세부 정보: 모든 매개변수가 포함된 전체 요청 URL(민감한 데이터 마스크)
응답 데이터: HTTP 상태 코드, 응답 본문 및 헤더
오류 컨텍스트: 오류 메시지, 사유 필드, 오류 분류
장치 정보: 특정 사용자의 문제 해결을 위한 장치 식별자
타임스탬프: 타임스탬프: 요청 시간, 응답 시간, 재시도 타임스탬프
재시도 메타데이터: 시도 횟수, 백오프 지연 및 최종 결과

모니터링 메트릭: 유형별 오류율, 재시도 성공률, 평균 응답 시간, 실패한 요청 볼륨을 추적하여 연동 문제를 사전에 파악하세요.

성공 응답

성공적인 API 응답은 Singular의 시스템에서 처리를 위해 수락된 요청을 나타냅니다.

HTTP 200 - 성공

HTTP 응답 설명

200 - ok

응답 본문에 오류나 이유가 없는 200 - 확인 응답은 요청이 처리를 위해 대기열로 성공적으로 전송되었음을 나타냅니다.

성공 표시기: 상태 필드에 "확인"이 포함되고 응답에 "이유" 필드가 없습니다.

응답 구조:

{
    "status": "ok"
}

처리 참고: "확인" 상태는 처리를 위해 대기열에 대기 중인 요청을 확인하지만 보고서에서 즉각적인 가시성을 보장하지는 않으므로 Singular 플랫폼에서 데이터를 검증하기 전에 처리 시간을 허용하세요.

오류 응답

오류 응답은 요청 실패에 대한 자세한 정보를 제공하여 신속한 문제 해결 및 해결을 가능하게 합니다.

매개변수 오류

필수 매개변수 누락

HTTP 응답 설명

200 - error

이유와 함께 응답합니다: missing argument: {param}

원인: 요청에 필수 매개변수가 누락되었거나 매개변수 값이 비어 있거나 널입니다.

복구할 수 없는 오류: 이 오류는 잘못된 요청 구조를 나타냅니다. 매개변수 문제를 해결하지 않고 재시도하지 마세요.

해결방법:

요청에 포함된 모든 필수 파라미터를 확인합니다.
매개변수 값이 널 또는 빈 문자열이 아닌지 확인합니다.
매개변수 철자 및 대소문자 구분 확인
엔드포인트 문서에서 전체 매개변수 목록을 검토하세요.

응답 예시:

{
    "status": "error",
    "reason": "missing argument: a"
}

일반적인 누락 매개변수 a (API 키), p (플랫폼), i (앱 식별자), ip(IP 주소), 기기 식별자

플랫폼 오류

잘못된 플랫폼 값

HTTP 응답 설명

200 - error

이유와 함께 응답합니다: invalid platform: {platform}

원인: 플랫폼 매개변수 값이 지원되는 플랫폼 목록에 없거나 형식이 잘못되었습니다(대소문자 구분).

복구할 수 없는 오류: 잘못된 매개변수 값을 수정한 후 다시 제출해야 합니다.

지원되는 플랫폼:

Android - Android 모바일 플랫폼
iOS - iOS 모바일 플랫폼
Web - 웹 애플리케이션
PC - 데스크톱 애플리케이션
Xbox - Xbox 게임 플랫폼
Playstation - PlayStation 게임 플랫폼
Nintendo - 닌텐도 게임 플랫폼
MetaQuest - 메타 퀘스트 VR 플랫폼
CTV - 커넥티드 TV 플랫폼

해상도:

플랫폼 값이 지원 목록과 정확히 일치하는지 확인합니다(대소문자 구분).
오타 또는 띄어쓰기 문제 확인
애플리케이션에 적합한 플랫폼 확인

응답 예시:

{
    "status": "error",
    "reason": "invalid platform: Desktop"
}

일반적인 실수: 'PC' 대신 '데스크톱' 사용, 소문자 플랫폼 이름 또는 지원되지 않는 플랫폼 값 사용

디바이스 식별자 오류

누락된 디바이스 식별자

HTTP 응답 설명

200 - error

이유와 함께 응답합니다: no device ID supplied

원인: 지정된 플랫폼에 필요한 장치 식별자가 누락되었습니다.

복구할 수 없는 오류입니다: 어트리뷰션에 필요한 디바이스 식별자입니다. 유효한 식별자가 없으면 요청을 처리할 수 없습니다.

해결방법:

요청에 플랫폼별 디바이스 식별자를 포함하세요.
iOS: idfv (항상 필수) 및 idfa(사용 가능한 경우)을 포함하세요.
Android(Google Play): asid (항상 필수) 및 aifa (사용 가능한 경우)을 포함하세요.
Android(Amazon): amid 포함
Android(중국 OEM): oaid 포함
웹/PC/콘솔/TV: sdid 포함

응답 예시:

{
    "status": "error",
    "reason": "no device ID supplied"
}

플랫폼별 식별자 문서 전체는 디바이스 식별자 요구 사항을참조하세요.

200 - error

이유와 함께 응답: platform: {platform} should have an {identifier} param

원인: 플랫폼이 지정되었지만 해당 플랫폼에 필요한 디바이스 식별자가 누락되었거나 잘못된 식별자 유형이 제공되었습니다.

복구할 수 없는 오류입니다: 플랫폼 식별자가 일치하지 않아 어트리뷰션이 불가능합니다. 올바른 식별자가 필요합니다.

일반적인 시나리오:

idfv 파라미터가 없는 iOS 플랫폼
asid 파라미터가 없는 안드로이드(구글 플레이) 플랫폼
sdid 파라미터가 없는 PC/웹/콘솔 플랫폼
지정된 플랫폼에 잘못된 식별자 유형 사용

해결방법

지정된 플랫폼의 식별자 유형이 올바른지 확인합니다.
식별자 파라미터 이름이 플랫폼 요구 사항과 일치하는지 확인합니다.
식별자 값이 널 또는 비어 있지 않은지 확인

응답 예시:

{
    "status": "error",
    "reason": "platform: PC should have an sdid param"
}

네트워크 및 인프라 오류

200이 아닌 HTTP 상태 코드

HTTP 응답 설명

4xx / 5xx

200이 아닌 HTTP 상태 코드는 인프라 또는 네트워크 문제를 나타냅니다.

재시도 가능 오류: 이러한 오류는 일반적으로 기하급수적 백오프 재시도 메커니즘을 일시적으로 구현합니다.

일반적인 상태 코드:

429 - 속도 제한 초과(더 긴 백오프 구현)
500 - 내부 서버 오류(지수 백오프로 재시도)
502/503/504 - 게이트웨이/서비스 오류(백오프 후 재시도)

해결방법:

지수 백오프를 사용한 재시도 로직 구현
모니터링 및 중요를 위한 오류 로그
오류가 지속되는 경우 Singular 지원팀에 문의
Singular 상태 페이지에서 서비스 문제 확인

전송률 제한: 429 오류가 발생하면 요청 속도를 줄이고 요청 스로틀링을 구현하여 한도 내에서 유지하세요.

오류 분류

오류 유형을 이해하면 적절한 재시도 로직을 적용하고 문제를 더 빠르게 해결할 수 있습니다.

재시도 가능 오류와 재시도 불가능 오류

재시도 불가 오류

이러한 오류는 재제출 전에 수동 수정이 필요한 잘못된 요청 매개변수 또는 구성을 나타냅니다.

오류 패턴	필요한 조치
`missing argument: {param}`	요청에 누락된 매개변수 추가
`invalid platform: {platform}`	플랫폼 값을 지원되는 옵션으로 수정
`no device ID supplied`	필수 장치 식별자 포함
`platform: {platform} should have an {identifier} param`	지정된 플랫폼에 대한 올바른 식별자 추가

재시도 가능 오류

이러한 오류는 지수 백오프를 사용하여 재시도를 시도하면 해결될 수 있는 일시적인 문제를 나타냅니다.

오류 유형	재시도 전략
200이 아닌 HTTP 상태 코드	지수 백오프를 사용한 재시도(2~3회 시도)
네트워크 시간 초과	지수 백오프로 재시도(3~5회 시도)
연결 오류	지수 백오프로 재시도(3~5회 시도)
속도 제한 오류(429)	더 긴 백오프 지연, 요청 속도 감소

결정 논리: 이유 필드 내용에 따라 오류를 분류합니다. "유효하지 않음", "누락됨" 또는 "있어야 함"이 포함된 오류는 일반적으로 재시도할 수 없습니다. 인프라 오류(시간 초과, 연결 실패, 5xx 코드)는 재시도할 수 있습니다.

문제 해결 가이드

일반적인 API 연동 문제 해결을 위한 빠른 참조입니다.

일반적인 문제 및 해결 방법

매개변수 문제

증상	해결 방법
누락된 인수: a	`a` 파라미터에 SDK 키 포함 개발자 도구에서가져오기 API 키가 아닌 SDK 키 사용
잘못된 플랫폼 오류	대소문자를 구분하는 올바른 플랫폼 값 사용 지원되는 플랫폼 목록과 대조하여 확인 오타 및 올바른 대문자 사용 여부 확인
제공된 디바이스 ID 없음	플랫폼별 디바이스 식별자 포함 iOS: `idfv` 필수, `idfa`선택 사항 Android: `asid` 필수(Google Play) 플랫폼별 요구 사항을 참조하세요.
플랫폼에 식별자가 있어야 합니다.	식별자 유형과 플랫폼 일치 PC에는 모바일 식별자가 아닌 `sdid` 가 필요합니다. iOS에는 Android 식별자가 아닌 `idfv` 가 필요합니다.

요청 유효성 검사 체크리스트

비행 전 유효성 검사: 일반적인 오류를 방지하기 위해 요청을 보내기 전에 다음 항목을 확인합니다.

SDK 키(a)가 포함되어 있고 올바른지(리포팅 API 키가 아님)
플랫폼 (p) 값이 지원 목록과 정확히 일치하는지
앱 식별자(i)가 플랫폼 유형과 일치합니다(iOS의 경우 번들 ID, Android의 경우 패키지 이름).
디바이스 식별자가 플랫폼에 적합하고 널/비어 있지 않아야 합니다.
IP 주소 (ip) 또는 use_ip=true 포함
모바일 플랫폼의 경우 OS 버전 (ve) 포함
엔드포인트에 필요한 모든 파라미터 포함
필요한 경우 URL 인코딩된 파라미터 값(특히 e파라미터의 JSON)

지원 리소스

추가 도움말

오류 처리 및 문제 해결을 구현한 후에도 문제가 지속되는 경우:

문서: 전체 S2S API 문서검토
테스트: SDK 콘솔을사용하여 연동 검증하기
지원: 오류 로그, 요청 예제 및 기기 식별자를 사용하여 Singular 지원팀에 문의하세요.
상태: 서비스 인시던트에 대한 Singular 시스템 상태 확인

서버 간 - API 응답 코드 및 오류

S2S API 응답 코드 및 오류 처리

응답 아키텍처

HTTP 상태 코드 동작

오류 처리 전략

구현 모범 사례

지수 백오프 구현

로깅 및 모니터링

성공 응답

HTTP 200 - 성공

오류 응답

매개변수 오류

필수 매개변수 누락

플랫폼 오류

잘못된 플랫폼 값

디바이스 식별자 오류

누락된 디바이스 식별자

네트워크 및 인프라 오류

200이 아닌 HTTP 상태 코드

오류 분류

재시도 가능 오류와 재시도 불가능 오류

재시도 불가 오류

재시도 가능 오류

문제 해결 가이드

일반적인 문제 및 해결 방법

매개변수 문제

요청 유효성 검사 체크리스트

지원 리소스

추가 도움말