Anleitung zu Kontingenten und Transaktionsraten

FedEx erhält jeden Tag viele Tausende API-Anfragen. Um dieses große Volumen zu bewältigen, werden drei Drosselungsmechanismen eingesetzt. Kontingente, Transaktionsraten und Grenzwerte sorgen dafür, dass FedEx Ressourcen effektiv und effizient eingesetzt werden.

Kontingente werden pro Organisation und pro API-Projekt festgelegt.

Kontingente pro Organisation

Das Transaktionskontingent ist die maximal zulässige Anzahl von API-Anfragen einer Organisation innerhalb eines Tages. Das bedeutet, dass API-Konsument*innen die Gesamtzahl der API-Anfragen berücksichtigen müssen, die für alle Projekte innerhalb ihrer Organisation abgesendet wurden. Die Anfragen werden gleich angerechnet, unabhängig von der Menge der Daten, die in der FedEx API-Antwort zurückgegeben werden.

Beispiel: Eine Organisation hat ein Kontingent von 500.000 API-Anfragen pro Tag. Wenn diese Organisation innerhalb der ersten Stunden des Tages 500.000 Anfragen abgesendet hat, ist das Kontingent ausgeschöpft. Für den Rest des Tages wird der Fehlercode „429 – Zu viele Anfragen – Tägliches Transaktionskontingent überschritten. Versuchen Sie es nach 01:00 Uhr des Folgetages (12:00 AM GTM) erneut.“ zurückgegeben.

Kontingente pro API-Projekt

Dieses Kontingent wird auf zwei unterschiedlichen Ebenen angewendet: Projekt und Funktionalität.

Was ist mit Funktionalität gemeint?

Jede API wird je nach bereitgestellten Funktionalitäten einer Gruppe zugeteilt. Jede Funktionalitätsgruppe umfasst einen oder mehrere Endpunkte. Beispielsweise hat die Sendungsverfolgungs-API-Funktionalität 6 API-Endpunkte, während die Adressprüfungsfunktionalität nur über einen API-Endpunkt verfügt.

Das Standardkontingent für „Pro Funktionalität pro Projekt“ (Per Capability Per Project, PCPP) für die Sendungsverfolgungsfunktionalität beträgt 100.000 Anfragen pro Tag. Das bedeutet, wenn bei der Sendungsverfolgungsfunktionalität Datenverkehr von einem beliebigen Projekt innerhalb einer Organisation an einen beliebigen der sechs Endpunkte diesen Grenzwert überschreitet, wird für den Rest des Tages der Fehlercode „429 – Zu viele Anfragen“ zurückgegeben. Dies gilt auch für alle nachfolgenden Sendungsverfolgungsanfragen an einen der sechs Endpunkte.

Beispiel: Wenn ein Projekt einen Grenzwert von 100.000 Anfragen pro Sendungsverfolgungsfunktionalität (mit sechs Endpunkten) hat, werden alle Transaktionen aller sechs Endpunkte auf den Grenzwert von 100.000 Anfragen aufsummiert. Wenn Ihr Projekt diesen Grenzwert überschreitet, wird bei nachfolgenden Sendungsverfolgungsanfragen der Fehlercode „429 – Zu viele Anfragen – Transaktionskontingent überschritten“ für den Rest des Tages bis 01:00 Uhr des Folgetages zurückgegeben.

Transaktionsraten

Bei allen Projekten gilt eine Begrenzung von 1.400 Transaktionen in einem Zeitraum von 10 Sekunden. Wenn dieser Grenzwert innerhalb des Zeitraums überschritten wird, erfolgt eine Drosselung.

Wird der Grenzwert in den ersten Sekunden erreicht, betrifft die Drosselung sämtliche Transaktionen, die in den verbleibenden Sekunden des 10-sekündigen Zeitraums gesendet werden. Während dieser Drosselung wird ein Fehler-Code mit der Meldung „429 – Too many requests“ zurückgegeben.

Wenn FedEx in den ersten zwei Sekunden 1.400 Anfragen erhält, betrifft die Drosselung alle nachfolgenden Übertragungen in den nächsten acht Sekunden. Zudem wird die Fehlermeldung „429 – Zu viele Anfragen – Wir haben in zu kurzer Zeit zu viele Anfragen empfangen. Bitte versuchen Sie es in Kürze erneut.“ zurückgegeben.

Nach Ablauf der zehn Sekunden wird die Drosselung aufgehoben und ein weiterer Zähler gestartet, der die Anzahl der Anfragen in den nächsten zehn Sekunden erfasst.

Grenzwerte

Grenzwerte werden auf der Ebene der IP-Adresse angewendet. Das erhöht die Resilienz des FedEx API-Autorisierungsprozesses. Dieser Mechanismus gilt nur für den Auth-Token-Generierungsservice. Es gibt zwei Arten von Grenzwerten:

1. Burst-Grenzwert: Drei Aufrufe pro Sekunde, kontinuierlich, während einer Zeitspanne von fünf Sekunden
2. Durchschnittsgrenzwert: Ein Aufruf pro Sekunde, kontinuierlich, während einer Zeitspanne von zwei Minuten

• Sobald eine öffentliche IP-Adresse einen dieser Grenzwerte überschreitet, erfolgt für zehn Minuten eine entsprechende Drosselung und alle weiteren Anfragen während dieses zehnminütigen Zeitraums erhalten den Statuscode „403 Forbidden“.
• Wenn API-Konsument*innen während dieser Drosselung Grenzwerte weiterhin überschreiten, wird die Drosselung verlängert. API-Nutzer*innen können die Drosselung beenden, indem sie den Grenzwert in den nächsten zehn Minuten nicht überschreiten.
• Die Grenzwertmechanismen basieren auf der öffentlichen IP-Adresse einer Benutzerin oder eines Benutzers. Wenn ein*e Benutzer*in zehn virtuelle Maschineninstanzen hinter einer öffentlichen IP-Adresse einrichtet, werden alle Anfragen von dieser IP-Adresse auf den Grenzwert angerechnet.

Traffic-Management

Jeder dieser drei Mechanismen bezieht sich auf einen bestimmten Aspekt des Traffic-Managements:

• Kontingente werden auf Ebene der Organisation angewendet – der kombinierte Traffic aller APIs einer Organisation wird auf das Transaktionskontingent angerechnet.

• Kontingente werden auf Ebene des Projekts angewendet – der kombinierte Traffic aller APIs einer Organisation wird auf das Transaktionskontingent angerechnet.

• Die Grenzen der Transaktionsraten gelten auf Projektebene: Der kombinierte Datenverkehr, der von allen APIs innerhalb eines Projekts erzeugt wird, unterliegt dieser Grenze.

• Die Grenzwerte werden auf der Ebene der IP-Adresse angewendet.

Hinweis: FedEx kann die Grenzwerte der oben erläuterten Drosselungsmechanismen herabsetzen, um Missbrauch, übermäßige Nutzung und Fehlverhalten zu verhindern. FedEx behält sich das Recht vor, die Zuteilung ohne vorherige Ankündigung zu ändern, um einen gerechten Zugang für API-Konsument*innen zu gewährleisten und die FedEx Ressourcen effektiv und effizient zu verteilen.

FAQ

Werden alle API-Transaktionen einer Organisation aus verschiedenen Projekten auf das Kontingent angerechnet?
Das Kontingent wird auf Organisationsebene angewendet. Einer Organisation können ein oder mehrere Projekte zugeordnet und jedem Projekt können eine oder mehrere APIs zugeordnet sein. Folglich wird der kombinierte Datenverkehr, der von allen APIs der verschiedenen Projekte – die zur selben Organisation gehören – erzeugt wird, auf das tägliche Kontingent angerechnet.

Wenn derselbe 429-Fehler sowohl für einen Kontingentverstoß als auch für einen Verstoß gegen die Frequenz zurückgegeben wird, wie kann ich dann feststellen, welche Art von Verstoß erfolgt ist?
Informationen zum Verstoß entnehmen Sie bitte der Fehlermeldung.

Wie lässt sich ein Grenzwertverstoß beheben?
Ein OAuth-Token ist eine Stunde lang gültig. Wir schlagen vor, dass API-Konsument*innen dieses Token für diese volle Stunde verwenden und erst dann ein neues Token anfordern, wenn das vorherige abläuft.

Was passiert, wenn der Grenzwert überschritten wird?
Sowohl fünf Sekunden als auch zwei Minuten sind Beobachtungsfenster für den Burst-Grenzwert bzw. den Durchschnittsschwellenwert. Wird in einem dieser Zeitfenster einer der beiden Grenzwerte von einer IP-Adresse aus überschritten, kommt es zu einer entsprechenden Drosselung.

Beispiel: Wenn eine IP-Adresse zwei Sekunden lang 3 Treffer pro Sekunde aufweist, gefolgt von einer Trefferquote von weniger als 3 Treffern pro Sekunde, dann ist der Häufungsgrenzwert nicht überschritten. Erfolgen von einer IP-Adresse aus jedoch fünf Sekunden hintereinander drei Aufrufe pro Sekunde und dann 15 Aufrufe in fünf Sekunden, dann wird der Häufungsgrenzwert von 14 Aufrufen in fünf Sekunden überschritten.