Documento

Códigos de resposta e tratamento de erros da API S2S

Compreender os códigos de resposta da API S2S da Singular e implementar o tratamento adequado de erros garante uma integração robusta com transmissão de dados fiável e precisão de atribuição.

Arquitetura de resposta

Comportamento do código de status HTTP

Compreensão crítica: Ao integrar com a API da Singular, todas as respostas retornam códigos de status HTTP 200, exigindo validação do campo 'status' do corpo da resposta para determinar o sucesso ('ok') ou falha ('erro').

O payload da resposta inclui um campo'reason' que fornece informações detalhadas sobre o erro quando o status é'error'.

Estrutura da resposta: Todas as respostas da API seguem um formato JSON consistente, independentemente do sucesso ou da falha, permitindo uma análise padronizada e o tratamento de erros em todas as interações do ponto final.

Estratégia de tratamento de erros

Melhores práticas de implementação

Implementar uma estratégia abrangente de tratamento de erros para garantir a integridade dos dados e a fiabilidade do sistema.

Abordagem recomendada:

Mecanismo de repetição: implemente a repetição de backoff exponencial com tentativas máximas configuráveis
Processamento seqüencial: Manter a ordem dos pedidos durante as tentativas para garantir a consistência dos dados
Classificação de erros: Distinguir entre erros que podem ser repetidos e erros que não podem ser repetidos (parâmetros inválidos não devem ser repetidos)
Registo exaustivo: Registar todos os pedidos falhados, incluindo parâmetros originais, mensagens de erro, identificadores de dispositivos e carimbos de data/hora
Monitorização e alertas: Acompanhar as tentativas de repetição e implementar um sistema de notificação para falhas críticas

Implementação de backoff exponencial

O backoff exponencial evita a sobrecarga dos servidores durante falhas temporárias e fornece uma estratégia de repetição eficiente.

Estratégia de repetição:

Atraso inicial: Começar com um atraso de 1-2 segundos após a primeira falha
Multiplicador de backoff: Duplica o tempo de atraso em cada nova tentativa subsequente (2s → 4s → 8s → 16s)
Máximo de tentativas: Configurar o limite (recomendado: 3-5 tentativas)
Atraso máximo: Limitar o atraso a um limite razoável (por exemplo, 60 segundos)
Jitter: Adicionar jitter aleatório para evitar o efeito de rebanho trovejante

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;
    }
}

Registo e monitorização

O registo abrangente permite uma rápida resolução de problemas e fornece visibilidade da integridade da integração.

Registo de informações essenciais:

Detalhes da solicitação: URL completo da solicitação com todos os parâmetros (mascara dados confidenciais)
Dados de resposta: Código de status HTTP, corpo da resposta e cabeçalhos
Contexto do erro: Mensagem de erro, campo de motivo e classificação do erro
Informações do dispositivo: Identificadores de dispositivos para a resolução de problemas de utilizadores específicos
Carimbos de data/hora: Tempo de solicitação, tempo de resposta e carimbos de data/hora de nova tentativa
Metadados de nova tentativa: Número da tentativa, atraso do backoff e resultado final

Métricas de monitorização: Acompanhe as taxas de erro por tipo, taxas de sucesso de novas tentativas, tempos médios de resposta e volume de pedidos falhados para identificar problemas de integração de forma proactiva.

Resposta bem-sucedida

As respostas bem-sucedidas da API indicam que a solicitação foi aceita para processamento pelos sistemas da Singular.

HTTP 200 - Sucesso

Resposta HTTP Descrição

200 - ok

A resposta 200 - ok sem erro ou motivo no corpo da resposta indica que a solicitação foi enviada com sucesso para a fila de processamento.

Indicador de sucesso: O campo de estado contém "ok" e não existe um campo de "motivo" na resposta.

Estrutura da resposta:

{
    "status": "ok"
}

Processamento Nota: o estado "ok" confirma que o pedido foi colocado em fila de espera para processamento, mas não garante a visibilidade imediata nos relatórios - permitir tempo de processamento antes de validar os dados na plataforma Singular.

Respostas de erro

As respostas de erro fornecem informações detalhadas sobre falhas de solicitação, permitindo a rápida solução de problemas e resolução.

Erros de parâmetros

Parâmetros obrigatórios ausentes

Resposta HTTP Descrição

200 - error

Resposta com motivo: missing argument: {param}

Causa: Parâmetro necessário em falta no pedido ou valor do parâmetro vazio/nulo.

Erro não repetível: Este erro indica uma estrutura de pedido inválida. Não tente novamente sem corrigir o problema do parâmetro.

Resolução:

Verificar todos os parâmetros necessários incluídos no pedido
Confirmar se os valores dos parâmetros não são cadeias nulas ou vazias
Verifique a ortografia dos parâmetros e a sensibilidade das maiúsculas e minúsculas
Rever a documentação do ponto final para obter a lista completa de parâmetros

Exemplo de resposta:

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

Parâmetros comuns em falta: a (chave de API), p (plataforma), i (identificador de aplicação), ip(endereço IP), identificadores de dispositivo

Erros de plataforma

Valor de plataforma inválido

Resposta HTTP Descrição

200 - error

Resposta com motivo: invalid platform: {platform}

Causa: O valor do parâmetro Plataforma não consta da lista de plataformas suportadas ou está incorretamente formatado (sensível a maiúsculas e minúsculas).

Erro não repetível: O valor de parâmetro inválido requer correção antes de ser reenviado.

Plataformas suportadas:

Android - Plataforma móvel Android
iOS - Plataforma móvel iOS
Web - Aplicações Web
PC - Aplicações de ambiente de trabalho
Xbox - Plataforma de jogos Xbox
Playstation - Plataforma de jogos PlayStation
Nintendo - Plataforma de jogos Nintendo
MetaQuest - Plataforma Meta Quest VR
CTV - Plataforma de televisão ligada

Resolução:

Verificar se o valor da plataforma corresponde exatamente à lista suportada (sensível a maiúsculas e minúsculas)
Verificar se existem erros tipográficos ou problemas de espaçamento
Confirmar a plataforma adequada para a sua aplicação

Exemplo de resposta:

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

Erros comuns: Usar "desktop" em vez de "PC", nomes de plataforma em minúsculas ou valores de plataforma não suportados

Erros de identificador de dispositivo

Identificador de dispositivo ausente

Resposta HTTP Descrição

200 - error

Resposta com motivo: no device ID supplied

Causa: Pedido sem o identificador de dispositivo necessário para a plataforma especificada.

Erro não repetível: Identificador de dispositivo necessário para atribuição. O pedido não pode ser processado sem um identificador válido.

Resolução:

Incluir identificador de dispositivo específico da plataforma no pedido
iOS: Incluir idfv (sempre necessário) e idfa(quando disponível)
Android (Google Play): Incluir asid(sempre necessário) e aifa (quando disponível)
Android (Amazon): Incluir amid
Android (OEMs chineses): Incluir oaid
Web/PC/Console/CTV: Incluir sdid

Exemplo de resposta:

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

Consulte os Requisitos do identificador de dispositivopara obter a documentação completa do identificador específico da plataforma.

200 - error

Resposta com motivo: platform: {platform} should have an {identifier} param

Causa: Plataforma especificada mas identificador de dispositivo necessário para essa plataforma em falta ou tipo de identificador incorreto fornecido.

Erro não repetível: A incompatibilidade do identificador de plataforma impede a atribuição. É necessário o identificador correto.

Cenários comuns:

Plataforma iOS sem o parâmetro idfv
Plataforma Android (Google Play) sem o parâmetro asid
Plataforma PC/Web/Console sem o parâmetro sdid
Utilização de um tipo de identificador incorreto para a plataforma especificada

Resolução:

Verificar o tipo de identificador correto para a plataforma especificada
Assegurar que o nome do parâmetro do identificador corresponde aos requisitos da plataforma
Confirmar que o valor do identificador não é nulo ou vazio

Exemplo de resposta:

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

Erros de rede e infraestrutura

Códigos de estado HTTP não-200

Resposta HTTP Descrição

4xx / 5xx

Qualquer código de estado HTTP diferente de 200 indica um problema de infraestrutura ou de rede.

Erro repetível: Estes erros são tipicamente transitórios e implementam um mecanismo de repetição de backoff exponencial.

Códigos de estado comuns:

429 - Limite de taxa excedido (implementar backoff mais longo)
500 - Erro interno do servidor (repetir com backoff exponencial)
502/503/504 - Erros de gateway/serviço (repetir com backoff)

Resolução:

Implementar lógica de repetição com backoff exponencial
Registar os erros para monitorização e alerta
Contactar o suporte da Singular se os erros persistirem
Verificar a página de status do Singular para problemas de serviço

Limitação de taxa: Se estiver recebendo erros 429, reduza a taxa de solicitação e implemente a limitação de solicitação para ficar dentro dos limites.

Classificação de erros

Entender os tipos de erro permite uma lógica de repetição apropriada e uma resolução mais rápida do problema.

Recuperáveis vs Não Recuperáveis

Erros não recuperáveis

Estes erros indicam parâmetros de pedido ou configuração inválidos que requerem correção manual antes de serem reenviados.

Padrão de erro	Ação necessária
`missing argument: {param}`	Adicionar parâmetro em falta ao pedido
`invalid platform: {platform}`	Corrigir o valor da plataforma para a opção suportada
`no device ID supplied`	Incluir o identificador de dispositivo necessário
`platform: {platform} should have an {identifier} param`	Adicionar identificador correto para a plataforma especificada

Erros que podem ser repetidos

Estes erros indicam problemas temporários que podem ser resolvidos com tentativas de repetição utilizando o backoff exponencial.

Tipo de erro	Estratégia de repetição
Códigos de estado HTTP não-200	Repetição com backoff exponencial (2-3 tentativas)
Timeouts de rede	Nova tentativa com retrocesso exponencial (3-5 tentativas)
Erros de ligação	Repetir com retrocesso exponencial (3-5 tentativas)
Erros de limite de taxa (429)	Atraso de backoff mais longo, reduzir a taxa de pedidos

Lógica de decisão: Classifique os erros com base no conteúdo do campo de motivo. Os erros que contêm "inválido", "em falta" ou "deveria ter" não são tipicamente repetíveis. Os erros de infraestrutura (timeouts, falhas de ligação, códigos 5xx) são repetíveis.

Guia de resolução de problemas

Referência rápida para a resolução de problemas comuns de integração de API.

Problemas comuns e soluções

Problemas de parâmetros

Sintoma	Solução
Argumento em falta: a	Incluir a chave SDK no parâmetro `a` Obter a partir das Ferramentas do Programador Utilizar a chave SDK, NÃO a chave da API de relatórios
Erro de plataforma inválida	Utilizar o valor correto da plataforma sensível a maiúsculas e minúsculas Verificar na lista de plataformas suportadas Verifique se há erros de digitação e capitalização correta
Não foi fornecido um ID de dispositivo	Incluir identificador de dispositivo específico da plataforma iOS: `idfv` obrigatório, `idfa`opcional Android: `asid` obrigatório (Google Play) Consultar os requisitos específicos da plataforma
A plataforma deve ter um identificador	Corresponder o tipo de identificador à plataforma PC requer `sdid`, não identificadores móveis iOS requer `idfv`, não identificadores Android

Lista de verificação da validação do pedido

Validação antes do voo: Verifique estes itens antes de enviar pedidos para evitar erros comuns.

Chave do SDK (a) incluída e correta (não a chave da API de comunicação)
O valor da plataforma (p) corresponde exatamente à lista suportada
O identificador da aplicação (i) corresponde ao tipo de plataforma (ID do pacote para iOS, nome do pacote para Android)
Identificador de dispositivo adequado à plataforma e não nulo/vazio
Endereço IP (ip) ou use_ip=true incluído
Versão do SO (ve) incluída para plataformas móveis
Todos os parâmetros necessários para o ponto final incluídos
Valores de parâmetro codificados por URL quando necessário (especialmente JSON no parâmetro e)

Recursos de suporte

Ajuda adicional

Se os problemas persistirem após a implementação do tratamento de erros e da resolução de problemas:

Documentação: Reveja a documentaçãocompleta da API S2S
Testes: Validar a integração utilizando a Consola SDK
Suporte: Contactar o Suporte Singular com registos de erros, exemplos de pedidos e identificadores de dispositivos
Status: Verificar o status do sistema Singular para incidentes de serviço

Servidor a servidor - Códigos de resposta e erros da API

Códigos de resposta e tratamento de erros da API S2S

Arquitetura de resposta

Comportamento do código de status HTTP

Estratégia de tratamento de erros

Melhores práticas de implementação

Implementação de backoff exponencial

Registo e monitorização

Resposta bem-sucedida

HTTP 200 - Sucesso

Respostas de erro

Erros de parâmetros

Parâmetros obrigatórios ausentes

Erros de plataforma

Valor de plataforma inválido

Erros de identificador de dispositivo

Identificador de dispositivo ausente

Erros de rede e infraestrutura

Códigos de estado HTTP não-200

Classificação de erros

Recuperáveis vs Não Recuperáveis

Erros não recuperáveis

Erros que podem ser repetidos

Guia de resolução de problemas

Problemas comuns e soluções

Problemas de parâmetros

Lista de verificação da validação do pedido

Recursos de suporte

Ajuda adicional