API de plateforme numérique - Contraintes d’utilisation de l’API

Cet article fournit des informations sur les contraintes rencontrées lors de l’utilisation des API.

Limitation d’entrée et de sortie

Pour garantir de bonnes performances, les services sur la plateforme implémentent une limitation du débit aux niveaux de l’utilisateur et du service. Ces limites, définies par le service, peuvent changer au fil du temps.

Lorsque les utilisateurs rencontrent des demandes à débit limité, l’API répond avec l’un des deux codes de réponse, ainsi que les en-têtes appropriés, pour indiquer la raison et la procédure à suivre :

1. L’erreur HTTP 429 (Trop de requêtes) indique que l’utilisateur a dépassé le nombre maximal d’appels utilisateur à ce service.

   1. Cela indique toujours une réponse à débit limité, mais pour des détails spécifiques, reportez-vous aux en-têtes et à la réponse. Certaines applications peuvent imposer des limitations supplémentaires qui déclenchent une erreur 429, mais elles fournissent des informations supplémentaires sur l’emplacement et la raison de la limite.

   2. Les requêtes générales à débit limité de plateforme incluent l’en-tête x-ratelimit-code .

2. Le protocole HTTP 503 (service non disponible) se produit lorsque le service est submergé par les requêtes et limite les nouvelles demandes.

   1. Si la valeur 503 provient de la limitation de débit, un x-ratelimit-code en-tête est présent.

Si vous rencontrez plus d’appels à débit limité que prévu, contactez votre représentant de compte Xandr.

Messages d’erreur

Si vous dépassez la limite de limitation, l’API répond avec le code de réponse HTTP 429 ou HTTP 503.

Si vous utilisez un script, vous devez case activée pour le code de réponse 429 ou un code 503 qui inclut également l’en-têtex-ratelimit-code. Si vous recevez ce code, veillez votre script pour le numéro retourné dans le Retry-After champ de l’en-tête de réponse. Ce champ vous indique combien de temps la limite de limitation est réinitialisée et vous pouvez continuer à envoyer des demandes d’API.

En-têtes d’erreur 429

Les demandes limitées au niveau de l’utilisateur retournent un 429 avec les en-têtes de limite de débit suivants :

1. x-ratelimit-code: correspond au code HTTP retourné lorsque le débit de l’appel a été limité.
2. retry-after: indique le temps d’attente en secondes avant de réessayer la requête.
3. x-ratelimit-count: affiche le nombre total d’appels que l’utilisateur a effectués au cours de la période limite. Les utilisateurs peuvent faire référence à ce numéro pour ajuster leurs modèles d’appel lorsqu’ils voient des demandes à débit limité.
4. x-an-user-id: ID utilisateur limité.

Exemple d’en-têtes de requête à débit limité 429 :

< 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 

503 en-têtes d’erreur

Les demandes limitées au niveau du service retournent un 503 avec les en-têtes de limite de débit suivants :

1. x-ratelimit-code: correspond au code HTTP retourné lorsque le débit de l’appel a été limité.
2. retry-after: indique le temps d’attente en secondes avant de réessayer la requête.

Exemple d’en-têtes de requête à débit limité 503 :

< 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 

En-têtes déconseillés

Les en-têtes suivants dans les réponses sont déconseillés et seront supprimés à l’avenir. Ils ne fournissent plus d’informations pertinentes. Ajustez tous les scripts à l’aide de ceux-ci pour utiliser les nouveaux en-têtes comme décrit ci-dessus.

• x-count-read
• x-count-write
• x-rate-limits
• x-ratelimit-read
• x-ratelimit-write
• x-ratelimit-system

Paramètre de débogage

En plus du code de réponse et de l’en-tête de réponse, chaque réponse de l’API contient un dbg_info paramètre. Ce paramètre contient des informations sur l’appel et la réponse d’API. Voici un exemple de cette sortie de débogage, qui inclut tous les avertissements reçus de l’API, la version de l’API utilisée pour l’appel qui a généré cette réponse et le service utilisé.

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

Pagination

Le nombre maximal d’objets pouvant être retournés dans une réponse GET donnée est de 100. Pour récupérer plus de 100 objets, vous pouvez paginer les résultats en spécifiant start_element et num_elements dans la chaîne de requête de la requête GET. Par exemple, la requête suivante retourne les 50 premiers objets dans la réponse :

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

Pour récupérer les 50 suivants, vous devez simplement définir start_element=50.

• Le premier élément est l’élément 0.
• Toutes les réponses GET auront une propriété « count » indiquant le nombre total d’éléments correspondant à cette requête GET.
• Cela s’applique également aux services qui ne sont pas des services de création de rapports, tels que le service de recherche créative, qui sont demandés avec des méthodes autres que les GET.

Exemple

$ 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'

Fréquence d’authentification

Après l’authentification, votre jeton reste valide pendant 2 heures. Vous n’avez pas besoin de vous authentifier à nouveau dans ce délai. Si vous vous authentifiez à nouveau, notez la limitation suivante : L’API vous permet de vous authentifier correctement 10 fois par période de 5 minutes. Toutes les tentatives d’authentification suivantes dans ces 5 minutes entraînent une erreur.

Limites des objets

Xandr limite le nombre d’éléments de ligne, de campagnes, de créations, d’éditeurs, de sites et de placements que vous pouvez avoir sur la plateforme. En outre, Xandr limite le nombre de domaines pouvant être utilisés dans une liste de domaines unique et le nombre de cibles qui peuvent être utilisées dans un seul profil. Vous pouvez utiliser le service de limite d’objets pour afficher vos limites et surveiller de manière proactive votre utilisation.

Pour la plupart des clients, les limites d’objets par défaut sont les suivantes :

FAQ

Comment savoir que j’approche de ma limite pour un objet ?

Nous vous envoyons une notification par e-mail lorsque vous atteignez 85 % et 95 % de votre limite pour un objet et un autre e-mail lorsque vous atteignez 100 % de votre limite.

Qui reçoit les Notifications par e-mail de limite d’objets ?

Les e-mails de notification de limite d’objets sont envoyés aux adresses e-mail spécifiées dans le sherlock_notify_email champ du service membre. Vous pouvez modifier les destinataires à tout moment. Notez, toutefois, que ce champ contrôle également les destinataires des e-mails d’audit créatif.

Que se passe-t-il si j’atteigne ma limite pour un objet ?

Lorsque vous approchez ou atteignez votre limite pour les campagnes, les éléments de ligne, les placements, les sites ou les éditeurs, vous devez supprimer toutes les instances inactives, inutilisées ou inutiles afin de rester sous votre limite. Les éléments de ligne supprimés, les campagnes, les créations, les éditeurs, les sites et les placements continuent d’apparaître dans les rapports, mais ne peuvent pas être supprimés.

Lorsque vous approchez ou atteignez votre limite de créations, vous devez supprimer les créations non expirées. Les éléments créatifs non expirés ont le is_expired champ défini sur false. Notez que la suppression des créations expirées n’aura pas d’impact sur votre nombre de créations.

Que se passe-t-il si je dépasse déjà ma limite ?

Si vous avez besoin de créer des objets supplémentaires, mais que vous avez déjà atteint ou dépassé votre limite, comme indiqué ci-dessus, supprimez les objets inutilisés ou contactez le support technique pour obtenir de l’aide. Notre équipe de support peut vous aider à identifier les objets inactifs à supprimer.

Ma limite peut-elle être augmentée ?

Dans des cas exceptionnels, une limite peut être temporairement levée par une petite quantité à la discrétion de notre équipe d’ingénierie. Contactez votre représentant Xandr pour discuter de cette option.