Compartir a través de

API de plataforma digital: restricciones de uso de API

  • Artículo

En este artículo se proporciona información sobre las restricciones a las que se enfrentan al usar las API.

Limitación de entrada y salida

Para garantizar un buen rendimiento, los servicios de la plataforma implementan la limitación de velocidad tanto en los niveles de usuario como de servicio. Estos límites, establecidos por el servicio, pueden cambiar con el tiempo.

Cuando los usuarios encuentran solicitudes limitadas por velocidad, la API responderá con uno de los dos códigos de respuesta, junto con los encabezados pertinentes, para indicar el motivo y cómo proceder:

  1. Http 429 (demasiadas solicitudes) indica que el usuario ha superado el número máximo de llamadas de usuario a este servicio.

    1. Esto siempre indica una respuesta de velocidad limitada, pero para obtener detalles específicos, consulte los encabezados y la respuesta. Algunas aplicaciones pueden imponer limitaciones adicionales que desencadenan un error 429, pero proporcionarán información adicional sobre la ubicación y el motivo del límite.

    2. Las solicitudes limitadas de velocidad de plataforma general incluirán el x-ratelimit-code encabezado .

  2. EL HTTP 503 (Servicio no disponible) se produce cuando el servicio está sobrecargado por las solicitudes y limita las nuevas.

    1. Si el 503 procede de la limitación de velocidad, habrá un x-ratelimit-code encabezado.

Si está experimentando más llamadas con tarifas limitadas de las previstas, póngase en contacto con el representante de su cuenta de Xandr.

Mensajes de error

Si supera el límite de limitación, la API responderá con el código de respuesta HTTP 429 o HTTP 503.

Si usa un script, debe buscar el código de respuesta 429 o un código 503 que también incluya el x-ratelimit-code encabezado. Si recibe este código, suspenda el script para el número devuelto en el Retry-After campo del encabezado de respuesta. Este campo le indica cuánto tiempo antes de restablecer el límite de limitación y puede seguir enviando solicitudes de API.

429 encabezados de error

Las solicitudes limitadas en el nivel de usuario devolverán un 429 con los siguientes encabezados de límite de velocidad:

  1. x-ratelimit-code: corresponde al código HTTP devuelto cuando la llamada era de velocidad limitada.
  2. retry-after: muestra el tiempo en segundos que se debe esperar antes de volver a intentar la solicitud.
  3. x-ratelimit-count: muestra el recuento total en las llamadas que el usuario ha realizado dentro del período límite. Los usuarios pueden hacer referencia a este número para ajustar sus patrones de llamadas al ver solicitudes de velocidad limitada.
  4. x-an-user-id: identificador de usuario limitado.

Ejemplo 429 de encabezados de solicitud limitados:

< HTTP/1.1 429 Too Many Requests 
< Server: nginx/1.11.10 
< Date: Fri, 02 Feb 2024 15:58:18 GMT 
< Content-Type: application/json; charset=utf-8 
< Content-Length: 358 
< Connection: keep-alive 
< Retry-After: 9 
< x-b3-traceid: 9f53184f6e2c3cb9 
< x-ratelimit-code: 429 
< x-an-user-id: 1234 
< x-ratelimit-count: 1000 
< retry-after: 24

Encabezados de error 503

Las solicitudes limitadas en el nivel de servicio devolverán un 503 con los siguientes encabezados de límite de velocidad:

  1. x-ratelimit-code: corresponde al código HTTP devuelto cuando la llamada era de velocidad limitada.
  2. retry-after: muestra el tiempo en segundos que se debe esperar antes de volver a intentar la solicitud.

Ejemplo 503 de encabezados de solicitud limitados:

< HTTP/1.1 429 Too Many Requests 
< Server: nginx/1.11.10 
< Date: Fri, 02 Feb 2024 15:58:18 GMT 
< Content-Type: application/json; charset=utf-8 
< Content-Length: 358 
< Connection: keep-alive 
< Retry-After: 9 
< x-b3-traceid: 9f53184f6e2c3cb9 
< x-ratelimit-code: 503 
< retry-after: 24

Encabezados en desuso

Los encabezados siguientes de las respuestas están en desuso y se quitarán en el futuro. Ya no proporcionan ninguna información relevante. Ajuste los scripts que los usen para usar los nuevos encabezados, como se describió anteriormente.

  • x-count-read
  • x-count-write
  • Límites de velocidad x
  • x-ratelimit-read
  • x-ratelimit-write
  • x-ratelimit-system

Parámetro de depuración

Además del código de respuesta y el encabezado de respuesta, cada respuesta de la API contendrá un dbg_info parámetro. Este parámetro contiene información sobre la llamada y la respuesta de la API. A continuación se muestra un ejemplo de esta salida de depuración, que incluye las advertencias recibidas de la API, la versión de API usada para la llamada que generó esta respuesta y el servicio usado.

{
  "response": {
    "status": "OK",
    ...
    "dbg_info": {
      "warnings": [],
      "version": "1.18.349",
      "output_term": "user"
    }
  }
  }

Paginación

El número máximo de objetos que se pueden devolver en una respuesta GET determinada es 100. Para recuperar más de 100 objetos, puede paginar los resultados especificando start_element y num_elements en la cadena de consulta de la solicitud GET. Por ejemplo, la siguiente solicitud devolvería los primeros 50 objetos de la respuesta:

$ curl -b cookies -c cookies 'https://api.appnexus.com/creative?start_element=0&num_elements=50'

Para recuperar los 50 siguientes, simplemente establecería start_element=50.

  • El primer elemento es el elemento 0.
  • Todas las respuestas GET tendrán una propiedad "count" que muestra el número total de elementos que coinciden con la solicitud GET.
  • Esto también se aplicará a los servicios que no son de informes, como el servicio de búsqueda creativa, que se solicitan con métodos distintos de los GET.

Ejemplo

$ curl -b cookies -c cookies 'https://api.appnexus.com/segment?start_element=0&num_elements=100'
$ curl -b cookies -c cookies 'https://api.appnexus.com/user?start_element=0&num_elements=100'

Frecuencia de autenticación

Después de autenticarse, el token permanece válido durante 2 horas. No es necesario volver a autenticarse en este momento. Si vuelve a autenticarse, tenga en cuenta la siguiente limitación: La API le permite autenticarse correctamente 10 veces por período de 5 minutos. Los intentos de autenticación posteriores en esos 5 minutos producirán un error.

Sugerencia

Se recomienda escuchar la error_id "NOAUTH" en las respuestas de llamada y volver a autenticarse solo después de recibirla.

Límites de objetos

Xandr limita el número de elementos de línea, campañas, creativos, editores, sitios y ubicaciones que puede tener en la plataforma. Además, Xandr limita el número de dominios que se pueden usar en una sola lista de dominios y el número de destinos determinados que se pueden usar en un único perfil. Puede usar el servicio de límite de objetos para ver los límites y supervisar de forma proactiva el uso.

Sugerencia

Para todos los tipos de objeto excepto las creatividades, los objetos activos e inactivos se cuentan con respecto al límite. En el caso de las creatividades, solo los objetos no expirados se cuentan con respecto al límite. Una creatividad expira cuando no se ha servido ni se ha modificado en 45 días.

Para la mayoría de los clientes, los límites de objetos predeterminados son los siguientes:

Objeto Límite
Creatividades por miembro

Nota: Solo las creatividades no expiradas se cuentan con este límite.		 10,000
Campañas por miembro 10,000
Elementos de línea por miembro 3,000
Ubicaciones por miembro 20,000
Sitios por miembro 10,000
Publicadores por miembro 3,000
Dominios por lista de dominios 30,000
Segmentos dirigidos por perfil 400
Grupos de segmentos dirigidos por perfil 400
Categorías de contenido destinadas por perfil 300
Categorías de contenido de plataforma destinadas por perfil 300
Códigos postales dirigidos por perfil 4000
Orígenes de inventario destinados por perfil En desuso
Publicadores destinados por perfil 300
Ubicación Grupos dirigida por perfil 100
Ubicaciones destinadas por perfil 250
Ofertas dirigidas por miembro (nota: solo las ofertas con perfiles se cuentan con este límite) 1000
Perfiles dirigidos por miembro 100

Preguntas frecuentes

¿Cómo sabré que estoy acercándome a mi límite para un objeto?

Le enviaremos una notificación por correo electrónico cuando alcance el 85 % y el 95 % de su límite para un objeto y otro correo electrónico cuando alcance el 100 % de su límite.

¿Quién recibe notificaciones por correo electrónico de límite de objetos?

Los correos electrónicos de notificación de límite de objetos se envían a las direcciones de correo electrónico especificadas en el sherlock_notify_email campo del servicio miembro. Puede cambiar los destinatarios en cualquier momento. Tenga en cuenta, sin embargo, que este campo controla también los destinatarios de los correos electrónicos de auditoría creativos.

¿Qué ocurre si alcanzo el límite de un objeto?

Cuando se aproxima o alcanza el límite de campañas, elementos de línea, ubicaciones, sitios o publicadores, debe eliminar cualquier instancia inactiva, no utilizada o innecesaria para que pueda permanecer por debajo del límite. Los elementos de línea eliminados, las campañas, los creativos, los editores, los sitios y las ubicaciones seguirán apareciendo en los informes, pero no se pueden recuperar.

Cuando se acerca o alcanza el límite para las creatividades, debe quitar las creatividades no expiradas. Las creatividades no expiradas tienen el is_expired campo establecido en false. Tenga en cuenta que la eliminación de las creatividades expiradas no afectará al recuento de creatividades.

¿Qué ocurre si ya supero mi límite?

Si necesita crear objetos adicionales, pero ya ha cumplido o superado el límite como se ha indicado anteriormente, elimine objetos no utilizados o póngase en contacto con el soporte técnico para obtener ayuda. Nuestro equipo de soporte técnico puede ayudarle a identificar los objetos inactivos que se van a eliminar.

¿Se puede aumentar mi límite?

En casos excepcionales, un límite puede ser elevado temporalmente por una pequeña cantidad a discreción de nuestro equipo de ingeniería. Póngase en contacto con su representante de Xandr para analizar esta opción.