S2S API Response Codes & Error Handling
Understanding Singular's S2S API response codes and implementing proper error handling ensures robust integration with reliable data transmission and attribution accuracy.
Response Architecture
HTTP Status Code Behavior
Critical Understanding: When integrating with Singular's API, all responses return HTTP 200 status codes, requiring validation of the response body's 'status' field to determine success ('ok') or failure ('error').
The response payload includes a 'reason' field providing detailed error information when status is 'error'.
Response Structure: All API responses follow consistent JSON format regardless of success or failure, enabling standardized parsing and error handling across all endpoint interactions.
Error Handling Strategy
Implementation Best Practices
Implement comprehensive error handling strategy to ensure data integrity and system reliability.
Recommended Approach:
- Retry Mechanism: Implement exponential backoff retry with configurable maximum attempts
- Sequential Processing: Maintain request order during retries to ensure data consistency
- Error Classification: Distinguish between retryable and non-retryable errors (invalid parameters should not retry)
- Comprehensive Logging: Log all failed requests including original parameters, error messages, device identifiers, and timestamps
- Monitoring & Alerts: Track retry attempts and implement notification system for critical failures
Exponential Backoff Implementation
Exponential backoff prevents overwhelming servers during temporary failures while providing efficient retry strategy.
Retry Strategy:
- Initial Delay: Start with 1-2 second delay after first failure
- Backoff Multiplier: Double delay time with each subsequent retry (2s → 4s → 8s → 16s)
- Maximum Attempts: Configure limit (recommended: 3-5 attempts)
- Maximum Delay: Cap delay at reasonable threshold (e.g., 60 seconds)
- Jitter: Add random jitter to prevent thundering herd effect
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;
}
} Logging & Monitoring
Comprehensive logging enables rapid troubleshooting and provides visibility into integration health.
Log Essential Information:
- Request Details: Full request URL with all parameters (mask sensitive data)
- Response Data: HTTP status code, response body, and headers
- Error Context: Error message, reason field, and error classification
- Device Information: Device identifiers for troubleshooting specific users
- Timestamps: Request time, response time, and retry timestamps
- Retry Metadata: Attempt number, backoff delay, and final outcome
Monitoring Metrics: Track error rates by type, retry success rates, average response times, and failed request volume to identify integration issues proactively.
Success Response
Successful API responses indicate request accepted for processing by Singular's systems.
HTTP 200 - Success
| HTTP Response | Description |
|---|---|
200 - ok
|
The 200 - ok response without error or reason in response body indicates request successfully sent to queue for processing. Success Indicator: Status field contains "ok" and no "reason" field present in response. Response Structure: Processing Note: "ok" status confirms request queued for processing but does not guarantee immediate visibility in reports—allow processing time before validating data in Singular platform. |
Error Responses
Error responses provide detailed information about request failures, enabling rapid troubleshooting and resolution.
Parameter Errors
Missing Required Parameters
| HTTP Response | Description |
|---|---|
200 - error
|
Response with reason: Cause: Required parameter missing from request or parameter value empty/null. Non-Retryable Error: This error indicates invalid request structure. Do not retry without fixing parameter issue. Resolution:
Response Example:
Common Missing Parameters: |
Platform Errors
Invalid Platform Value
| HTTP Response | Description |
|---|---|
200 - error
|
Response with reason: Cause: Platform parameter value not in list of supported platforms or incorrectly formatted (case-sensitive). Non-Retryable Error: Invalid parameter value requires correction before resubmission. Supported Platforms:
Resolution:
Response Example: Common Mistakes: Using "desktop" instead of "PC", lowercase platform names, or unsupported platform values |
Device Identifier Errors
Missing Device Identifier
| HTTP Response | Description |
|---|---|
200 - error
|
Response with reason: Cause: Request missing required device identifier for specified platform. Non-Retryable Error: Device identifier required for attribution. Request cannot be processed without valid identifier. Resolution:
Response Example: Refer to Device Identifier Requirements for complete platform-specific identifier documentation. |
200 - error
|
Response with reason:
Cause: Platform specified but required device identifier for that platform missing or incorrect identifier type provided. Non-Retryable Error: Platform-identifier mismatch prevents attribution. Correct identifier required. Common Scenarios:
Resolution:
Response Example: |
Network & Infrastructure Errors
Non-200 HTTP Status Codes
| HTTP Response | Description |
|---|---|
4xx / 5xx
|
Any non-200 HTTP status code indicates infrastructure or network issue. Retryable Error: These errors typically transient—implement exponential backoff retry mechanism. Common Status Codes:
Resolution:
Rate Limiting: If receiving 429 errors, reduce request rate and implement request throttling to stay within limits. |
Error Classification
Understanding error types enables appropriate retry logic and faster issue resolution.
Retryable vs Non-Retryable
Non-Retryable Errors
These errors indicate invalid request parameters or configuration requiring manual correction before resubmission.
| Error Pattern | Action Required |
|---|---|
missing argument: {param}
|
Add missing parameter to request |
invalid platform: {platform}
|
Correct platform value to supported option |
no device ID supplied
|
Include required device identifier |
platform: {platform} should have an {identifier} param
|
Add correct identifier for specified platform |
Retryable Errors
These errors indicate temporary issues that may resolve with retry attempts using exponential backoff.
| Error Type | Retry Strategy |
|---|---|
| Non-200 HTTP status codes | Retry with exponential backoff (2-3 attempts) |
| Network timeouts | Retry with exponential backoff (3-5 attempts) |
| Connection errors | Retry with exponential backoff (3-5 attempts) |
| Rate limit errors (429) | Longer backoff delay, reduce request rate |
Decision Logic: Classify errors based on reason field content. Errors containing "invalid", "missing", or "should have" are typically non-retryable. Infrastructure errors (timeouts, connection failures, 5xx codes) are retryable.
Troubleshooting Guide
Quick reference for resolving common API integration issues.
Common Issues & Solutions
Parameter Issues
| Symptom | Solution |
|---|---|
| Missing argument: a |
Include SDK Key in
|
| Invalid platform error |
Use correct case-sensitive platform value
|
| No device ID supplied |
Include platform-specific device identifier
|
| Platform should have identifier |
Match identifier type to platform
|
Request Validation Checklist
Pre-Flight Validation: Verify these items before sending requests to prevent common errors.
-
SDK Key (
a) included and correct (not Reporting API Key) -
Platform (
p) value matches supported list exactly -
App identifier (
i) matches platform type (Bundle ID for iOS, Package Name for Android) - Device identifier appropriate for platform and not null/empty
-
IP address (
ip) oruse_ip=trueincluded -
OS version (
ve) included for mobile platforms - All required parameters for endpoint included
-
Parameter values URL-encoded where necessary (especially JSON
in
eparameter)
Support Resources
Additional Help
If issues persist after implementing error handling and troubleshooting:
- Documentation: Review complete S2S API Documentation
- Testing: Validate integration using SDK Console
- Support: Contact Singular Support with error logs, request examples, and device identifiers
- Status: Check Singular system status for service incidents