> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manejo de Errores

> Guía completa de códigos de error y solución de problemas para las APIs de Topsort

# 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:

| Campo     | Tipo   | Descripción                                                |
| :-------- | :----- | :--------------------------------------------------------- |
| `errCode` | string | Cadena corta que identifica de forma única el problema     |
| `docUrl`  | string | Enlace a la documentación con más información              |
| `message` | string | Explicación legible opcional (puede cambiar con el tiempo) |

## Códigos de Estado HTTP

<CardGroup cols={2}>
  <Card title="400 - Solicitud Incorrecta" icon="circle-exclamation">
    Formato de solicitud inaceptable o sintaxis incorrecta. Verifique la estructura de la solicitud contra la especificación de la API.
  </Card>

  <Card title="403 - Prohibido" icon="lock">
    Problema con la clave API o falta de tokens de autorización. Verifique sus credenciales de autenticación.
  </Card>

  <Card title="404 - No Encontrado" icon="file-slash">
    El recurso no existe o la URL es incorrecta. Verifique la ruta del endpoint y el ID del recurso.
  </Card>

  <Card title="422 - Entidad No Procesable" icon="file-circle-xmark">
    El cuerpo de la solicitud no coincide con el modelo esperado. Faltan campos requeridos o tipos de datos incorrectos.
  </Card>

  <Card title="429 - Límite de Tasa" icon="gauge-high">
    Demasiadas solicitudes. Verifique los encabezados de límite de tasa: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
  </Card>

  <Card title="5xx - Error del Servidor" icon="server">
    Problema inesperado del servidor. Nuestro equipo normalmente soluciona estos problemas rápidamente. Consulte la página de estado.
  </Card>
</CardGroup>

## Códigos de Error Específicos

<AccordionGroup>
  <Accordion title="Errores de Autenticación">
    * **`invalid_api_key`** - La clave API en el encabezado de autorización falta, es inválida o ha expirado. Consulte [autenticación](/es/api-reference/authentication) para más detalles.
  </Accordion>

  <Accordion title="Errores de Formato de Solicitud">
    * **`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
  </Accordion>

  <Accordion title="Errores de Subasta">
    * **`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
  </Accordion>

  <Accordion title="Errores de Contexto y Ubicación">
    * **`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
  </Accordion>

  <Accordion title="Errores de Categoría">
    * **`invalid_category`** - Solo uno de `id`, `ids`, o `disjunctions` debe estar configurado, donde ningún array sea mayor que 5
  </Accordion>

  <Accordion title="Errores de Sesión">
    * **`invalid_opaque_user_id`** - El valor del ID de usuario opaco no debe tener más de 90 caracteres
  </Accordion>

  <Accordion title="Errores de Producto y Catálogo">
    * **`no_products`** - Se debe especificar al menos un producto
    * **`no_products_or_category`** - Se debe proporcionar al menos un ID de producto o un ID de categoría
    * **`too_many_products`** - Se excedió el límite de productos en la solicitud
    * **`product_info_mismatch`** - Los arrays de información del producto deben tener todos la misma longitud
    * **`invalid_quality_score`** - Los puntajes de calidad deben estar entre 0.0 y 1.0
    * **`non_positive_price`** - El precio del producto debe ser positivo
  </Accordion>

  <Accordion title="Errores de Segmentación Geográfica">
    * **`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
  </Accordion>

  <Accordion title="Errores de Dispositivo">
    * **`invalid_device`** - El dispositivo debe ser uno de: `desktop` o `mobile`
  </Accordion>

  <Accordion title="Errores de Búsqueda">
    * **`too_many_search_query_words`** - Se excedió el límite de palabras de consulta de búsqueda en la solicitud
  </Accordion>

  <Accordion title="Errores de Seguimiento de Eventos">
    * **`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`
  </Accordion>

  <Accordion title="Errores de Evento de Compra">
    * **`no_purchase_items`** - Se debe comprar al menos un artículo
    * **`missing_purchased_at`** - Falta el campo requerido `purchasedAt`
  </Accordion>

  <Accordion title="Errores de Marketplace y Proveedor">
    * **`invalid_marketplace`** - No existe tal marketplace
    * **`invalid_vendor`** - No existe tal proveedor
    * **`resource_not_found`** - No se encontró el recurso solicitado
  </Accordion>

  <Accordion title="Errores de Experimento">
    * **`experiment_variant_too_long`** - Las variantes de experimento de marketplace tienen una longitud máxima de 10 caracteres
  </Accordion>

  <Accordion title="Errores de Libro Mayor y Cuenta">
    * **`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
  </Accordion>

  <Accordion title="Errores de Filtro">
    * **`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
  </Accordion>

  <Accordion title="Errores de API de Viajes">
    * **`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
  </Accordion>

  <Accordion title="Errores del Servidor">
    * **`internal_server_error`** - El servidor ha encontrado un problema
    * **`request_canceled`** - El llamador canceló la solicitud
  </Accordion>
</AccordionGroup>

## Problemas Comunes de Integración

<CardGroup cols={2}>
  <Card title="Eventos No Aparecen" icon="eye-slash">
    **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`)
  </Card>

  <Card title="Resultados de Subasta Vacíos" icon="rectangle-xmark">
    **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
  </Card>

  <Card title="Problemas de Atribución" icon="link-slash">
    **La atribución no funciona correctamente:**

    * Consulte nuestra [Guía de Solución de Problemas de Atribución](/knowledge-base/ad-platform/reporting/attribution-troubleshooting)
    * Verifique que los IDs de oferta resueltos se pasen correctamente
    * Verifique que los eventos de compra incluyan los IDs de producto adecuados
  </Card>

  <Card title="Problemas de Conexión" icon="wifi-slash">
    **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
  </Card>
</CardGroup>

<Warning>
  **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.
</Warning>

## Errores de Validación Detallados

Algunos endpoints devuelven errores de validación detallados con información a nivel de campo:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Retroceso Exponencial" icon="arrows-rotate">
    Reintente solicitudes fallidas con retrasos crecientes entre intentos:

    ```python theme={null}
    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)
    ```
  </Card>

  <Card title="Use Encabezados de Límite de Tasa" icon="gauge">
    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.
  </Card>
</CardGroup>

<Note>
  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.
</Note>

## Problemas de Conexión y Red

### Lista de Verificación de Solución de Problemas

<Steps>
  <Step title="Pruebe la Conectividad Básica">
    Verifique que puede alcanzar la API de Topsort:

    ```bash theme={null}
    curl -I https://api.topsort.com
    ```
  </Step>

  <Step title="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`
  </Step>

  <Step title="Verifique el Soporte TLS">
    Asegúrese de que su cliente HTTP soporte versiones modernas de TLS:

    ```bash theme={null}
    openssl s_client -connect api.topsort.com:443
    ```
  </Step>

  <Step title="Configure Tiempos de Espera">
    Establezca valores de tiempo de espera apropiados e implemente lógica de reintento:

    ```python theme={null}
    session = requests.Session()
    session.timeout = (10, 30)  # (connect, read)
    ```
  </Step>

  <Step title="Consulte la Página de Estado">
    Visite [topsort.statuspage.io](https://topsort.statuspage.io) para el estado del servicio
  </Step>
</Steps>

### Problemas Comunes de Red

<AccordionGroup>
  <Accordion title="Problemas de Certificado SSL/TLS">
    **Síntomas:** Errores de validación de certificado, fallos de handshake SSL

    **Soluciones:**

    * 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`
  </Accordion>

  <Accordion title="Problemas de Firewall/Proxy">
    **Síntomas:** Conexión rechazada, solicitudes colgadas

    **Soluciones:**

    * 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
  </Accordion>

  <Accordion title="Problemas de Tiempo de Espera">
    **Síntomas:** Solicitudes agotando tiempo de espera, colgándose indefinidamente

    **Soluciones:**

    * 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
  </Accordion>

  <Accordion title="Conectividad Regional">
    **Síntomas:** Problemas desde regiones geográficas específicas

    **Soluciones:**

    * 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
  </Accordion>
</AccordionGroup>

## Herramientas de Depuración

<CardGroup cols={2}>
  <Card title="Registros de Desarrollador" icon="list-check">
    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](/api-reference/logs) para ayuda interpretando entradas de registro.
  </Card>

  <Card title="Página de Estado" icon="signal">
    Monitoree la salud del servicio y el mantenimiento planificado en [topsort.statuspage.io](https://topsort.statuspage.io)

    Suscríbase a actualizaciones para notificaciones en tiempo real.
  </Card>
</CardGroup>

## ¿Necesita Ayuda?

Si sigue experimentando problemas después de consultar esta guía:

* **Consulte la página de estado:** [topsort.statuspage.io](https://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