Códigos de respuesta de la API S2S y gestión de errores
Comprender los códigos de respuesta de la API S2S de Singular y aplicar una gestión de errores adecuada garantiza una integración sólida con una transmisión de datos y una precisión de atribución fiables.
Arquitectura de respuesta
Comportamiento del código de estado HTTP
Comprensión crítica: Cuando se integra con la API de Singular, todas las respuestas devuelven códigos de estado HTTP 200, que requieren la validación del campo "status" del cuerpo de la respuesta para determinar el éxito ("ok") o el fracaso ("error").
La carga útil de la respuesta incluye un campo"reason" que proporciona información detallada sobre el error cuando el estado es"error".
Estructura de la respuesta: Todas las respuestas de la API siguen un formato JSON coherente independientemente del éxito o el fracaso, lo que permite un análisis sintáctico y una gestión de errores estandarizados en todas las interacciones de los puntos finales.
Estrategia de gestión de errores
Mejores prácticas de implementación
Implemente una estrategia integral de gestión de errores para garantizar la integridad de los datos y la fiabilidad del sistema.
Enfoque recomendado:
- Mecanismo de reintento: Implemente un reintento exponencial con un máximo de intentos configurable.
- Procesamiento secuencial: Mantener el orden de las solicitudes durante los reintentos para garantizar la coherencia de los datos
- Clasificación de errores: Distinguir entre errores reintentables y no reintentables (los parámetros no válidos no deben reintentarse)
- Registro exhaustivo: Registro de todas las solicitudes fallidas, incluidos los parámetros originales, los mensajes de error, los identificadores de dispositivo y las marcas de tiempo.
- Supervisión y alertas: Seguimiento de los intentos de reintento e implementación de un sistema de notificación de fallos críticos.
Implementación de reintentos exponenciales
El backoff exponencial evita la saturación de los servidores durante los fallos temporales, al tiempo que proporciona una estrategia de reintento eficiente.
Estrategiade reintento:
- Retraso inicial: Comenzar con un retardo de 1-2 segundos tras el primer fallo
- Multiplicador de reintentos: Duplica el tiempo de retardo con cada reintento posterior (2s → 4s → 8s → 16s).
- Intentos Máximos: Configure el límite (recomendado: 3-5 intentos)
- Retardo Máximo: Limite el retardo a un umbral razonable (por ejemplo, 60 segundos)
- Fluctuación: Añada fluctuaciones aleatorias para evitar el efecto de rebaño atronador.
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;
}
} Registro y supervisión
Un registro exhaustivo permite la rápida resolución de problemas y proporciona visibilidad sobre el estado de la integración.
Registre la información esencial:
- Detalles de la solicitud: URL de solicitud completa con todos los parámetros (enmascarar datos confidenciales)
- Datos de respuesta: Código de estado HTTP, cuerpo de la respuesta y cabeceras
- Contexto del error: Mensaje de error, campo de motivo y clasificación del error
- Información del dispositivo: Identificadores de dispositivo para la resolución de problemas de usuarios específicos
- Marcas de tiempo: Tiempo de solicitud, tiempo de respuesta y marcas de tiempo de reintento
- Metadatos de reintento: Número de intentos, retardo de reintento y resultado final.
Métricas de supervisión: Seguimiento de las tasas de error por tipo, tasas de éxito de reintentos, tiempos de respuesta medios y volumen de solicitudes fallidas para identificar problemas de integración de forma proactiva.
Respuesta satisfactoria
Las respuestas satisfactorias de la API indican que la solicitud ha sido aceptada para su procesamiento por los sistemas de Singular.
HTTP 200 - Correcto
| Respuesta HTTP | Descripción |
|---|---|
200 - ok
|
La respuesta 200 - ok sin error o razón en el cuerpo de la respuesta indica que la solicitud se ha enviado correctamente a la cola para su procesamiento. Indicador de éxito: El campo de estado contiene "ok" y no hay ningún campo "reason" presente en la respuesta. Estructura de la respuesta: Nota de procesamiento: el estado "ok" confirma que la solicitud se ha puesto en cola para su procesamiento, pero no garantiza una visibilidad inmediata en los informes; espere un tiempo de procesamiento antes de validar los datos en la plataforma Singular. |
Respuestas de error
Las respuestas de error proporcionan información detallada sobre los fallos de la solicitud, lo que permite una rápida localización y resolución de problemas.
Errores de parámetros
Faltan parámetros obligatorios
| Respuesta HTTP | Descripción |
|---|---|
200 - error
|
Respuesta con motivo: Causa: Falta el parámetro requerido en la solicitud o el valor del parámetro está vacío/nulo. Error no recuperable: Este error indica que la estructura de la petición no es válida. No reintentar sin solucionar el problema del parámetro. Resolución:
Ejemplo de respuesta:
Parámetros comunes que faltan: |
Errores de plataforma
Valor de plataforma no válido
| Respuesta HTTP | Descripción |
|---|---|
200 - error
|
Respuesta con motivo: Causa: El valor del parámetro Plataforma no está en la lista de plataformas soportadas o tiene un formato incorrecto (distingue mayúsculas de minúsculas). Error no recuperable: El valor de parámetro no válido requiere corrección antes de reenviarse. Plataformas compatibles:
Resolución:
Ejemplo de respuesta: Errores comunes: Uso de "desktop" en lugar de "PC", nombres de plataforma en minúsculas o valores de plataforma no admitidos |
Errores de identificador de dispositivo
Falta el identificador de dispositivo
| Respuesta HTTP | Descripción |
|---|---|
200 - error
|
Respuesta con motivo: Causa: Falta el identificador de dispositivo requerido para la plataforma especificada. Error no recuperable: Se requiere un identificador de dispositivo para la atribución. La solicitud no puede procesarse sin un identificador válido. Resolución:
Ejemplo de respuesta: Consulte Requisitos delidentificador del dispositivopara obtener la documentación completa del identificador específico de la plataforma. |
200 - error
|
Respuesta con motivo: Causa: Plataforma especificada pero falta el identificador de dispositivo requerido para esa plataforma o se ha proporcionado un tipo de identificador incorrecto. Error no recuperable: La falta de coincidencia de identificador de plataforma impide la atribución. Se requiere el identificador correcto. Escenarios comunes:
Resolución:
Ejemplo de respuesta: |
Errores de red e infraestructura
Códigos de estado HTTP no-200
| Respuesta HTTP | Descripción |
|---|---|
4xx / 5xx
|
Cualquier código de estado HTTP no-200 indica un problema de infraestructura o de red. Error reintentable: Estos errores suelen ser transitorios e implementan un mecanismo de reintento exponencial. Códigos de estado comunes:
Resolución:
Limitación de velocidad: Si recibe errores 429, reduzca la tasa de peticiones e implemente un estrangulamiento de peticiones para mantenerse dentro de los límites. |
Clasificación de errores
Comprender los tipos de error permite una lógica de reintento adecuada y una resolución de problemas más rápida.
Reintentables vs No reintentables
Errores no reintentables
Estos errores indican parámetros de solicitud o configuración no válidos que requieren una corrección manual antes del reenvío.
| Patrón de error | Acción requerida |
|---|---|
missing argument: {param}
|
Añada el parámetro que falta a la solicitud |
invalid platform: {platform}
|
Corrija el valor de la plataforma a la opción admitida |
no device ID supplied
|
Incluir el identificador de dispositivo requerido |
platform: {platform} should have an {identifier} param
|
Añadir el identificador correcto para la plataforma especificada |
Errores reintentables
Estos errores indican problemas temporales que pueden resolverse con reintentos utilizando un backoff exponencial.
| Tipo de error | Estrategia de reintento |
|---|---|
| Códigos de estado HTTP no-200 | Reintento con retardo exponencial (2-3 intentos) |
| Tiempo de espera de red | Reintento con retardo exponencial (3-5 intentos) |
| Errores de conexión | Reintento con reintento exponencial (3-5 intentos) |
| Errores de límite de velocidad (429) | Mayor retardo, menor tasa de peticiones |
Lógica de decisión: Clasificar los errores basándose en el contenido del campo de motivo. Los errores que contienen "no válido", "falta" o "debería haber" normalmente no son reintentables. Los errores de infraestructura (tiempos de espera, fallos de conexión, códigos 5xx) son reintentables.
Guía de resolución de problemas
Referencia rápida para resolver problemas comunes de integración de API.
Problemas comunes y soluciones
Problemas de parámetros
| Síntoma | Solución |
|---|---|
| Falta el argumento: a |
Incluya SDK Key en el parámetro
|
| Error de plataforma no válida |
Utilice el valor de plataforma correcto que distinga entre mayúsculas y minúsculas
|
| No se ha proporcionado un identificador de dispositivo |
Incluya un identificador de dispositivo específico de la plataforma
|
| La plataforma debe tener un identificador |
Haga coincidir el tipo de identificador con la plataforma
|
Lista de comprobación para la validación de solicitudes
Validación previa al envío: Verifique estos elementos antes de enviar solicitudes para evitar errores comunes.
-
SDK Key (
a) incluida y correcta (no Reporting API Key) -
El valor de la plataforma (
p) coincide exactamente con la lista admitida -
El identificador de la aplicación (
i) coincide con el tipo de plataforma (Bundle ID para iOS, Package Name para Android) - Identificador de dispositivo apropiado para la plataforma y no nulo/vacío
-
Dirección IP (
ip) ouse_ip=trueincluida -
Versión del sistema operativo (
ve) incluida para plataformas móviles - Se incluyen todos los parámetros necesarios para el punto final
-
Valores de parámetros codificados mediante URL cuando sea necesario (especialmente JSON en el parámetro
e)
Recursos de soporte
Ayuda adicional
Si los problemas persisten después de aplicar la gestión de errores y la resolución de problemas:
- Documentación: Revise la documentacióncompleta de la API S2S
- Pruebas: Valide la integración mediante SDK Console
- Soporte: Póngase en contacto con Singular Support con registros de errores, ejemplos de solicitudes e identificadores de dispositivos
- Estado: Compruebe el estado del sistema Singular para incidencias de servicio