ドキュメント

S2S APIレスポンスコードとエラー処理

SingularのS2S APIレスポンスコードを理解し、適切なエラー処理を実装することで、信頼性の高いデータ送信とアトリビューション精度を備えた堅牢な統合を実現します。

レスポンスアーキテクチャ

HTTPステータスコードの動作

重要な理解SingularのAPIと統合する場合、全てのレスポンスはHTTP 200ステータスコードを返し、成功（'ok'）または失敗（'error'）を判断するために、レスポンスボディの'status'フィールドを検証する必要があります。

レスポンスのペイロードには'reason' フィールドがあり、ステータスが'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 - okレスポンスは、リクエストが処理キューに正常に送信されたことを示します。

成功の指標：Status フィールドは "ok" を含み、"reason" フィールドはレスポンスに存在しない。

応答構造：

{
    "status": "ok"
}

処理注：「ok」ステータスはリクエストが処理のためにキューに入れられたことを示しますが、レポートでの即時の可視性を保証するものではありません。

エラーレスポンス

エラーレスポンスはリクエストの失敗に関する詳細情報を提供し、迅速なトラブルシューティングと解決を可能にします。

パラメータエラー

必須パラメータの欠落

HTTP レスポンス説明

200 - error

理由を含むレスポンス：missing argument: {param}

原因原因: リクエストに必要なパラメータがないか、パラメータ値が空/nullです。

再試行不可能なエラー：このエラーは無効なリクエスト構造を示します。パラメータの問題を修正せずに再試行しないでください。

解決方法

リクエストに必要なパラメータがすべて含まれているか確認してください。
パラメータ値がNULLや空文字列でないことを確認する
パラメータのスペルや大文字と小文字の区別を確認する
パラメータの完全なリストについては、エンドポイントのドキュメントを確認してください。

レスポンスの例

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

よくあるパラメータの欠落： a (APIキー）、p （プラットフォーム）、i （アプリ識別子）、ip（IPアドレス）、デバイス識別子

プラットフォームのエラー

無効なプラットフォーム値

HTTP レスポンス説明

200 - error

理由を含むレスポンス：invalid platform: {platform}

原因原因: Platform パラメータ値がサポートされているプラットフォームのリストにないか、形式が正しくありません (大文字と小文字が区別されます)。

再送不可エラー：無効なパラメータ値のため、再提出の前に修正が必要です。

サポートされているプラットフォーム

Android - Androidモバイルプラットフォーム
iOS - iOSモバイルプラットフォーム
Web - ウェブアプリケーション
PC - デスクトップアプリケーション
Xbox - Xboxゲームプラットフォーム
Playstation - プレイステーション・ゲーム・プラットフォーム
Nintendo - 任天堂ゲームプラットフォーム
MetaQuest - Meta Quest VRプラットフォーム
CTV - コネクテッドTVプラットフォーム

解決方法

プラットフォームの値がサポートリストに正確に一致することを確認する（大文字と小文字を区別する
タイプミスやスペーシングの問題をチェック
アプリケーションに適したプラットフォームを確認する

応答例

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

よくある間違いPC」の代わりに「desktop」を使う、プラットフォーム名を小文字にする、またはサポートされていないプラットフォーム値を使う

デバイス識別子のエラー

デバイス識別子の欠落

HTTPレスポンス説明

200 - error

理由を含むレスポンス：no device ID supplied

原因原因: 指定されたプラットフォームに必要なデバイス識別子がありません。

再試行不可能なエラー：デバイス識別子は帰属に必要です。有効な識別子がない場合、リクエストは処理できません。

解決方法

リクエストにプラットフォーム固有のデバイス識別子を含める。
iOS：idfv （常に必要）とidfa（利用可能な場合）を含める。
Android (Google Play)：asid(常に必要) およびaifa (利用可能な場合) を含める。
Android（Amazon）：amidを含む。
Android（中国OEM）：oaidを含む
ウェブ/PC/コンソール/CTV：sdidを含む

レスポンスの例：

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

プラットフォーム固有の識別子に関する完全な文書については、『Device Identifier Requirements（デバイス識別子の要件）』を参照のこと。

200 - error

理由付きレスポンス：platform: {platform} should have an {identifier} param

原因原因：プラットフォームが指定されているが、そのプラットフォームに必要なデバイス識別子がないか、提供された識別子のタイプが正しくない。

再試行不可能なエラー：非再帰可能エラー：プラットフォーム識別子の不一致が帰属を妨げています。正しい識別子が必要です。

よくあるシナリオ

idfv パラメータがない iOS プラットフォーム
asid パラメータがない Android (Google Play) プラットフォーム
sdid パラメータがない PC/Web/Console プラットフォーム
指定されたプラットフォームに対して誤った識別子タイプを使用している

解決方法

指定されたプラットフォームの正しい識別子タイプを確認する
識別子のパラメータ名がプラットフォーム要件と一致していることを確認する。
識別子の値がNULLまたは空でないことを確認する。

レスポンスの例

{
    "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)	バックオフ遅延を長くし、リクエスト・レートを下げる

決定ロジック：理由フィールドの内容に基づいてエラーを分類する。 invalid」、「missing」、または「should have」を含むエラーは通常、再試行不可能である。インフラストラクチャエラー（タイムアウト、接続障害、5xxコード）は再試行可能である。

トラブルシューティングガイド

API統合に関する一般的な問題を解決するためのクイックリファレンスです。

一般的な問題と解決策

パラメータの問題

症状	解決方法
引数がない	`a` パラメータに SDK キーを含める開発者ツールから取得 SDKキーを使用してください。
無効なプラットフォームエラー	大文字と小文字を区別する正しいプラットフォーム値を使用してくださいサポートされているプラットフォームのリストと照合してください。タイプミスや大文字小文字が正しく入力されているか確認してください。
デバイスIDが提供されていない	プラットフォーム固有のデバイスIDを含める iOS:`idfv` 必須、`idfa`任意 Android:`asid` 必須（Google Play）プラットフォーム固有の要件を参照
プラットフォームが識別子を持つこと	識別子の種類をプラットフォームに合わせる PC には`sdid` が必要であり、モバイル識別子ではない iOSは`idfv` 、Androidの識別子は不要

リクエスト検証チェックリスト

飛行前の検証：一般的なエラーを防ぐため、リクエストを送信する前に以下の項目を確認してください。

SDK Key (a) が含まれており、正しい (Reporting API Key ではありません)
プラットフォーム (p) の値がサポートされるリストに正確に一致する。
アプリ識別子（i ）がプラットフォームタイプ（iOSの場合はバンドルID、Androidの場合はパッケージ名）と一致する。
デバイス識別子がプラットフォームに適切であり、NULL/空でないこと。
IP アドレス (ip) またはuse_ip=true を含む。
モバイルプラットフォーム用のOSバージョン(ve)を含む
エンドポイントに必要なパラメータをすべて含む
必要に応じてURLエンコードされたパラメータ値（特にeパラメータのJSON

サポートリソース

追加ヘルプ

エラー処理とトラブルシューティングを実施しても問題が解決しない場合は、以下のヘルプを参照してください：

ドキュメント： S2S APIドキュメンテーションをご参照ください。
テスト SDKコンソールを利用して、統合を検証する
サポートエラーログ、リクエスト例、デバイス識別子をSingularサポートに連絡してください。
ステータスの確認サービスインシデントのSingularシステムステータスの確認

サーバー間 - APIレスポンスコードとエラー

S2S APIレスポンスコードとエラー処理

レスポンスアーキテクチャ

HTTPステータスコードの動作

エラー処理戦略

実装のベストプラクティス

エクスポネンシャル・バックオフの実装

ロギングとモニタリング

成功レスポンス

HTTP 200 - 成功

エラーレスポンス

パラメータエラー

必須パラメータの欠落

プラットフォームのエラー

無効なプラットフォーム値

デバイス識別子のエラー

デバイス識別子の欠落

ネットワークとインフラストラクチャーのエラー

200以外のHTTPステータス・コード

エラーの分類

再試行可能エラーと再試行不可能エラー

再試行不可エラー

再試行可能なエラー

トラブルシューティングガイド

一般的な問題と解決策

パラメータの問題

リクエスト検証チェックリスト

サポートリソース

追加ヘルプ