Saltar al contenido principal

​
Errores

Al trabajar con las APIs de Topsort, puede encontrar varias respuestas de error. Esta guía le ayuda a comprender, diagnosticar y resolver problemas comunes.

​
Formato de Respuesta de Error

Las APIs de Topsort devuelven errores como arrays JSON que contienen objetos de error:
CampoTipoDescripción
errCodestringCadena corta que identifica de forma única el problema
docUrlstringEnlace a la documentación con más información
messagestringExplicación legible opcional (puede cambiar con el tiempo)

​
Códigos de Estado HTTP

400 - Solicitud Incorrecta

Formato de solicitud inaceptable o sintaxis incorrecta. Verifique la estructura de la solicitud contra la especificación de la API.

403 - Prohibido

Problema con la clave API o falta de tokens de autorización. Verifique sus credenciales de autenticación.

404 - No Encontrado

El recurso no existe o la URL es incorrecta. Verifique la ruta del endpoint y el ID del recurso.

422 - Entidad No Procesable

El cuerpo de la solicitud no coincide con el modelo esperado. Faltan campos requeridos o tipos de datos incorrectos.

429 - Límite de Tasa

Demasiadas solicitudes. Verifique los encabezados de límite de tasa: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

5xx - Error del Servidor

Problema inesperado del servidor. Nuestro equipo normalmente soluciona estos problemas rápidamente. Consulte la página de estado.

​
Códigos de Error Específicos

  • invalid_api_key - La clave API en el encabezado de autorización falta, es inválida o ha expirado. Consulte autenticación para más detalles.
  • bad_request - No se pudo analizar la solicitud
  • invalid_json - La solicitud no es JSON válido
  • empty_request - El cuerpo de la solicitud está vacío; asegúrese de enviar datos
  • request_canceled - El llamador canceló la solicitud
  • invalid_operation - La operación no es válida en el estado actual
  • missing_auctions - Debe especificar al menos una subasta
  • too_many_auctions - Máximo de 5 subastas pueden ejecutarse en paralelo
  • too_few_slots - Se debe especificar al menos un espacio en una subasta
  • missing_slots - Falta el campo requerido slots
  • invalid_auction_id - El ID de subasta no corresponde a una subasta válida
  • missing_promotion_type - Debe solicitar espacios para al menos un tipo de promoción
  • invalid_promotion_type - Tipos de promoción inválidos en el campo slots
  • invalid_context - Contexto inválido. Debe especificar como máximo dos de: lista de productos, consulta de búsqueda o categorías (para marcas patrocinadas: como máximo una)
  • invalid_placement_id - El ID de ubicación debe estar entre 1 y 8
  • missing_slot_id - Falta el ID de espacio requerido para anuncios de banner
  • invalid_category - Solo uno de id, ids, o disjunctions debe estar configurado, donde ningún array sea mayor que 5
  • invalid_opaque_user_id - El valor del ID de usuario opaco no debe tener más de 90 caracteres
  • invalid_geo_targeting - Segmentación geográfica inválida. Debe especificar location o locations
  • too_many_locations - Se pueden especificar como máximo 2 ubicaciones
  • invalid_location_cell - La celda de ubicación especificada no es una celda H3 válida
  • invalid_device - El dispositivo debe ser uno de: desktop o mobile
  • too_many_search_query_words - Se excedió el límite de palabras de consulta de búsqueda en la solicitud
  • invalid_event_time - Al menos un evento está en el futuro
  • invalid_resolved_bid_id - resolvedBidId inválido
  • invalid_use_of_external_campaign_id - No se puede establecer tanto resolvedBidId como externalCampaignId
  • no_purchase_items - Se debe comprar al menos un artículo
  • missing_purchased_at - Falta el campo requerido purchasedAt
  • invalid_marketplace - No existe tal marketplace
  • invalid_vendor - No existe tal proveedor
  • resource_not_found - No se encontró el recurso solicitado
  • experiment_variant_too_long - Las variantes de experimento de marketplace tienen una longitud máxima de 10 caracteres
  • no_listing_experiment_variant - Las variantes de experimento de marketplace solo son compatibles con subastas de listado patrocinado
  • account_unique_violation - La solicitud rompe la restricción única de cuenta del libro mayor
  • invalid_ledger_account - La cuenta del libro mayor no existe
  • insufficient_balance - Saldo insuficiente
  • different_currencies - Ambas cuentas deben tener el mismo código de moneda
  • equal_from_and_to - From y to deben ser diferentes
  • bad_request (operación de filtro) - La operación de filtro puede ser and u or
  • bad_request (atributos) - El número de atributos de filtro debe estar entre 1 y 3
  • bad_request (promociones) - El número de promociones de filtro debe estar entre 1 y 3
  • invalid_travel_category - La categoría de viaje debe ser una cadena no vacía si se proporciona
  • invalid_travel_date_range - La fecha de finalización debe ser mayor que la fecha de inicio
  • too_many_passengers - El número de pasajeros debe ser menor que diez
  • invalid_traveler_type - El tipo de viajero debe ser uno de: family, group, solo, couple
  • invalid_date_format - La fecha debe seguir el formato YYYY-MM-DD (ej., 2012-05-08)
  • invalid_travel_type - El tipo debe ser uno de: hotels, flights
  • missing_variation_id - Falta el ID de variación
  • missing_flight_travel_context - Faltan campos del contexto de viaje de vuelo
  • internal_server_error - El servidor ha encontrado un problema
  • request_canceled - El llamador canceló la solicitud

​
Problemas Comunes de Integración

Eventos No Aparecen

Los eventos devuelven 200 pero no aparecen en el panel:
  • Verifique que occurredAt esté dentro de los últimos 30 días
  • Verifique que el producto exista en el catálogo
  • Confirme la ortografía del tipo de evento (click, no Click)

Resultados de Subasta Vacíos

Las subastas no devuelven ganadores:
  • Verifique el presupuesto de la campaña (problema más común)
  • Verifique que el saldo de la cuenta sea positivo
  • Confirme que los productos estén en stock y activos
  • Verifique que existan campañas activas
  • Verifique que los montos de las ofertas no sean demasiado bajos

Problemas de Atribución

La atribución no funciona correctamente:

Problemas de Conexión

Conexión rechazada o tiempo de espera agotado:
  • Pruebe la conectividad: curl -I https://api.topsort.com
  • Verifique que el firewall permita HTTPS saliente (puerto 443)
  • Incluya en lista blanca los dominios *.topsort.com
  • Verifique la validación del certificado TLS/SSL
El agotamiento del presupuesto es la causa #1 de subastas vacías. Antes de depurar problemas complejos de subasta, primero verifique que sus campañas tengan suficiente presupuesto diario y saldo de cuenta. Las campañas con presupuesto cero no pueden participar en subastas.

​
Errores de Validación Detallados

Algunos endpoints devuelven errores de validación detallados con información a nivel de campo: 
{
  "error": "validation_error",
  "message": "Invalid request body",
  "details": [
    {
      "field": "events[0].productId",
      "message": "Product 'sku_999' not found in catalog"
    },
    {
      "field": "events[0].occurredAt",
      "message": "Timestamp cannot be in the future"
    }
  ]
}
Use el array details para identificar exactamente qué campos tienen problemas y qué necesita corregirse.

​
Limitación de Tasa

Retroceso Exponencial

Reintente solicitudes fallidas con retrasos crecientes entre intentos:
def retry_with_backoff(url, max_retries=5):
    delay = 1
    for i in range(max_retries):
        response = requests.get(url)
        if response.status_code != 429:
            return response
        time.sleep(delay)
        delay = min(delay * 2, 64)

Use Encabezados de Límite de Tasa

Respete los encabezados de límite de tasa en las respuestas:
  • X-RateLimit-Limit - Total de solicitudes permitidas
  • X-RateLimit-Remaining - Solicitudes restantes
  • X-RateLimit-Reset - Cuándo se restablece el límite
Espere hasta X-RateLimit-Reset antes de reintentar.
Los endpoints de Subastas (/v2/auctions) y Eventos (/v2/events) no tienen límite de tasa. Los límites de tasa se aplican a otros endpoints como las APIs de gestión de campañas y reportes.

​
Problemas de Conexión y Red

​
Lista de Verificación de Solución de Problemas

1

Pruebe la Conectividad Básica

Verifique que puede alcanzar la API de Topsort:
curl -I https://api.topsort.com
2

Verifique las Reglas del Firewall

Asegúrese de que el tráfico HTTPS saliente (puerto 443) esté permitido e incluya en lista blanca:
  • api.topsort.com
  • *.topsort.com
3

Verifique el Soporte TLS

Asegúrese de que su cliente HTTP soporte versiones modernas de TLS:
openssl s_client -connect api.topsort.com:443
4

Configure Tiempos de Espera

Establezca valores de tiempo de espera apropiados e implemente lógica de reintento:
session = requests.Session()
session.timeout = (10, 30)  # (connect, read)
5

Consulte la Página de Estado

Visite topsort.statuspage.io para el estado del servicio

​
Problemas Comunes de Red

Síntomas: Errores de validación de certificado, fallos de handshake SSLSoluciones:
  • Actualice su cliente HTTP para soportar versiones modernas de TLS
  • Asegúrese de que su sistema confíe en las autoridades de certificación estándar
  • Pruebe con: openssl s_client -connect api.topsort.com:443
Síntomas: Conexión rechazada, solicitudes colgadasSoluciones:
  • Incluya en lista blanca los dominios de Topsort (api.topsort.com, *.topsort.com)
  • Permita tráfico HTTPS saliente en el puerto 443
  • Configure ajustes de proxy si su red lo requiere
  • Pruebe sin proxy para aislar el problema
Síntomas: Solicitudes agotando tiempo de espera, colgándose indefinidamenteSoluciones:
  • Aumente los valores de tiempo de espera en su cliente HTTP
  • Implemente lógica de reintento con retroceso exponencial
  • Verifique cargas de solicitud grandes que excedan los límites
  • Use agrupación de conexiones para mejor rendimiento
Síntomas: Problemas desde regiones geográficas específicasSoluciones:
  • Pruebe desde diferentes ubicaciones para aislar problemas regionales
  • Use un servicio CDN o proxy si es necesario
  • Contacte a soporte con los detalles de su ubicación

​
Herramientas de Depuración

Registros de Desarrollador

Consulte la pestaña Dev Tools en su Plataforma de Anuncios para registros detallados de solicitudes/respuestas de API.Consulte nuestra guía de Registros de Desarrollador para ayuda interpretando entradas de registro.

Página de Estado

Monitoree la salud del servicio y el mantenimiento planificado en topsort.statuspage.ioSuscríbase a actualizaciones para notificaciones en tiempo real.

​
¿Necesita Ayuda?

Si sigue experimentando problemas después de consultar esta guía:
  • Consulte la página de estado: topsort.statuspage.io
  • Contacte a soporte con detalles del error y ejemplos de solicitudes de API
  • Revise la documentación de API para requisitos específicos del endpoint