Schnittstelle: Paketsperren und Drosseln

Die Schnittstelle begrenzt Anfragen auf zwei Arten: über das gebuchte Paket und über Zähler. Das Paket entscheidet, ob ein Weg überhaupt offensteht und welche Zahlgrenzen für Assistenten, Wissensquellen, Dokumente, Abschnitte und Sitzplätze beim Anlegen geprüft werden. Zähler begrenzen, wie oft ein Weg in einem Zeitfenster aufgerufen wird. Diese Seite nennt jede Sperre mit Weg, Wert und Antwort. Den Überblick über Pakete und Kontingent gibt Pakete und Kontingente.

Paketsperre und Paketgrenzen

Wege, die an ein Paketmerkmal, eine Ja/Nein-Grenze des Pakets oder eine Zahlgrenze gebunden sind, prüfen das Paket des Kontos, bevor sie etwas tun. Die Ablehnung trägt den Status 402 und unterscheidet sich damit von einer fehlenden Rolle (403): Eine Rolle kann jemand im Konto vergeben, ein fehlendes Merkmal oder eine höhere Grenze bringt nur ein anderes Paket. Eine Zahlgrenze gilt als erreicht, sobald der Bestand die Grenze erreicht. Bei einer Grenze von 1 scheitert also der zweite Assistent.

limit und feature nennen die Grenze oder das Merkmal mit dem Schlüssel aus den Tabellen unten. plan ist der Schlüssel des Pakets (etwa start, pro oder custom), plan_name sein Anzeigename (Start, Pro, Individuell). available_in listet die Schlüssel der Pakete, die das Merkmal enthalten. allowed ist die Grenze, used der Bestand. Ein Feld message tragen diese Antworten nicht, auch nicht ab Status 500; maßgeblich ist error.

{
  "error": "plan_limit_reached",
  "limit": "assistants",
  "allowed": 1,
  "used": 1,
  "plan": "start",
  "plan_name": "Start"
}

In der App erscheint bei plan_feature_missing „Der Tarif Start enthält diese Funktion nicht. Die Übersicht steht unter Abrechnung.“, bei plan_limit_reached „Die Grenze des Tarifs Start ist erreicht: 1 von 1. Die Übersicht steht unter Abrechnung.“ und bei jeder anderen 402 „Der gebuchte Tarif deckt das nicht ab. Die Übersicht steht unter Abrechnung.“ Statt „Start“ und der Zahlen stehen Ihr Paket und Ihr Stand. Eine 503 zeigt die App als „Der Dienst hat einen Fehler gemeldet. Bitte versuchen Sie es später erneut.“

Merkmale je Weg

Bei Werkzeugen prüft die Schnittstelle die Bauform beim Anlegen, beim Ändern und bei der Ausführung. Ohne das Merkmal wird ein Werkzeug dieser Bauform weder angelegt noch geändert; die Antwort ist dieselbe 402 mit plan_feature_missing. Die Bauformen für angebundene Systeme sind order_status, order_change, inventory_status, price_lookup, calendar_availability, calendar_booking, crm_lead, crm_activities, callback_note und ticket_create. Termine und Warenkörbe prüfen das Merkmal nur beim Ändern des Status; ihre Listen lassen sich ohne das Merkmal lesen und einzelne Vorgänge löschen. GET records zählt jede Art, und plan_locked nennt die Arten, deren Status sich nicht ändern lässt. conversation_export ist eine Ja/Nein-Grenze des Pakets; fehlt sie, antwortet die Schnittstelle ebenfalls mit 402 plan_feature_missing, feature ist dann conversation_export. Wie die App gesperrte Bereiche zeigt, steht unter Pakete und Kontingente.

Zahlgrenzen je Weg

Die Grenzen gelten je Konto. Geprüft wird der vorhandene Bestand, bevor der Weg etwas anlegt; ist eine Grenze erreicht, entsteht nichts Neues. Dokumente und Abschnitte entstehen erst beim Einlesen einer Quelle, die Prüfung vergleicht also den Bestand vor dem Einlesen mit der Grenze. Das Wiederherstellen einer Quelle prüft keine Zahlgrenze. Bei seats zählen Mitglieder und offene Einladungen zusammen. Mehr zu Sitzplätzen steht unter Team und Rollen.

Die Höhe jeder Grenze je Paket nennt Pakete und Kontingente. Bei einer Ablehnung stehen die Grenze Ihres Kontos in allowed und der Bestand in used.

Benannte Drosseln

Neben dem Paket begrenzen benannte Drosseln die Zahl der Aufrufe. Jeder Name hat eigene Zähler, ein erschöpfter Name sperrt also nur die Wege, die ihn tragen. Die Werte gelten je Minute; wo zusätzlich eine Stundenzahl steht, zählt sie getrennt, und die Anfrage wird abgewiesen, sobald einer der beiden Zähler erschöpft ist. Eine Überschreitung ergibt 429, in der App erscheint „Zu viele Versuche. Bitte warten Sie einen Moment.“ Allgemeines zu den Statuscodes steht unter Grundlagen der Schnittstelle.

Je Person

Diese Drosseln zählen je angemeldeter Person. Ohne Anmeldung zählt ersatzweise die Herkunft der Anfrage. Wer mehreren Konten angehört, nutzt denselben Zähler in allen Konten; nur dpa zählt je Konto und Person getrennt. password-change ist ein gemeinsamer Zähler für drei Wege.

Je Herkunft

Diese Drosseln gelten für Wege ohne Anmeldung und zählen je Herkunft: bei IPv4 je Adresse, bei IPv6 je /64-Netz. Eine IPv4-Adresse in IPv6-Schreibweise (::ffff:) zählt als IPv4-Adresse. Minuten- und Stundenzähler laufen getrennt.

Je Besucher

Die Wege des Widgets unter /api/v1/public/widget/{key} zählen je Besucher, gebildet aus Herkunft und Widget-Schlüssel zusammen. Besucher mit derselben Herkunft teilen sich den Zähler also nur innerhalb desselben Widget-Schlüssels. Zusätzlich gelten die Deckel des Widgets.

Deckel eines API-Schlüssels

Die Wege unter /api/v1/integration melden sich mit dem Kopf X-Api-Key an, siehe Schnittstelle für Anbindungen. Für sie gelten zwei Deckel, beide gezählt je Schlüssel. Eine aus dem Ruder gelaufene Anbindung hält so die übrigen Schlüssel des Kontos nicht an.

• Beide Deckel werden geprüft, bevor einer von beiden zählt. Eine abgewiesene Anfrage verbraucht also nichts. Gezählt wird aber vor der Prüfung des Bereichs: eine Anfrage, die erst am fehlenden Bereich scheitert, zählt auf beiden Deckeln mit.
• Seine Minutengrenze meldet ein Schlüssel über GET /api/v1/integration/status im Feld limit_per_min, siehe Schnittstelle: Integration.
• Einen bestehenden Schlüssel können Sie nicht ändern. Für einen anderen Minutenwert legen Sie einen neuen Schlüssel an und ziehen den alten zurück.
• Ein Konto hat höchstens 10 gültige Schlüssel; zurückgezogene und abgelaufene zählen nicht mit. Ein weiterer ergibt 422 mit too_many_keys und limit, in der App „Die Höchstzahl gleichzeitiger Schlüssel ist erreicht.“
• GET /api/v1/keys nennt die Grenze in limit_active. Die Seite Schnittstellen zeigt den Stand unter API-Schlüssel etwa als „3 / 10“.

{
  "error": "too_many_requests",
  "scope": "minute",
  "limit": 120,
  "retry_after": 42,
  "limit_per_min": 120,
  "wait": 42
}

scope ist minute oder day, limit der überschrittene Deckel und limit_per_min der Minutenwert des Schlüssels. retry_after und wait enthalten dieselbe Wartezeit in Sekunden wie der Kopf Retry-After. Beim Tagesdeckel reicht sie bis zum Tagesende nach UTC, mindestens aber 60 Sekunden.

Deckel des Widgets

Neben den benannten Drosseln hat das Widget zwei eigene Deckel, deren Werte am Konto hängen: einen für Aufrufe und einen für Fragen. Jeder Deckel zählt auf dem Besucher und, wenn der Aufruf zu einem Gespräch gehört, zusätzlich auf dieser Sitzung im Chatfenster. Zu einem Gespräch gehört ein Aufruf, wenn die Gesprächskennung im Pfad oder als conversation_id im Rumpf steht. Jeder Träger kann abweisen; gezählt wird erst, wenn keiner abgewiesen hat.

• Der Minutenwert für Aufrufe ist der Wert Anfragen je Minute des Kontos. Ein Wechsel auf ein Paket setzt ihn auf dessen Wert: 20 bei Start, 60 bei Pro, 120 bei Individuell. Ist das Konto bereits Individuell, bleibt ein dort hinterlegter Wert stehen.
• Die Tagesgrenze der Aufrufe ist derselbe Wert wie der Tagesdeckel der API-Schlüssel. Für Fragen kann für ein Konto ein anderer Wert als die Vorgabe hinterlegt sein.
• Hochladen und Abrufen von Anhängen fallen nicht unter diese Deckel, dort gelten nur die benannten Drosseln.
• Die Zeitfenster laufen ab dem ersten gezählten Aufruf: 60 Sekunden für die Minute und 86.400 Sekunden für den Tag. Der Tag ist hier kein Kalendertag.
• Ein Deckel unter 1 gilt als abgeschaltet.
• Die Ablehnung lautet 429 mit too_many_requests, limit_per_min, limit_per_day und wait, dazu der Kopf Retry-After.
• Wie das Chatfenster darauf reagiert, steht unter Widget-Auslieferung.

Monatskontingent

Ist das Kontingent des Monats erschöpft, erzeugt der Assistent keine Antworten mehr. Wie das sichtbar wird, hängt vom Weg ab. Das Kontingent selbst beschreibt Pakete und Kontingente.

Schon ab 80 % des Kontingents antwortet der Assistent gedrosselt: eine Antwort ist dann auf 300 Einheiten begrenzt und dreht höchstens eine Werkzeugrunde. Ist das Kontingent aufgebraucht, lehnt der Dienst die Frage ab, bevor eine Antwort erzeugt wird.

Weitere Zähler

Einige Wege zählen zusätzlich selbst. Ihre Ablehnungen tragen eigene Fehlerkennungen.

Bei der Anmeldung zählen nur Fehlversuche. Eine erfolgreiche Anmeldung gibt den Zähler aus E-Mail-Adresse und Herkunft frei, der Zähler je Herkunft läuft weiter. retry_in nennt die Wartezeit in Sekunden; einen Kopf Retry-After senden Anmeldung und Passwort-Anforderung nicht. Die Grenze von 10 Mails je E-Mail-Adresse ändert die Antwort nicht, die Anfrage endet mit 200. Wartet oder läuft für das Konto schon ein Abgleich, prüft POST catalog/shop/sync die Sperrzeit nicht und antwortet mit 202; already_pending ist dann true.

Umgang mit Ablehnungen

• Unterscheiden Sie nach Status: 402 verlangt ein anderes Paket, 403 eine andere Rolle, 429 eine Pause und 503 mit plan_limit_unmeasured einen späteren Versuch.
• Liegt der Kopf Retry-After vor, warten Sie mindestens so viele Sekunden. Sonst werten Sie retry_after, wait oder retry_in aus.
• Wiederholen Sie eine 402 nicht in einer Schleife. Sie ändert sich erst mit einem anderen Paket oder einem kleineren Bestand, etwa nach dem Löschen eines Assistenten.
• Geben Sie jeder Anbindung einen eigenen Schlüssel. Minuten- und Tagesdeckel zählen je Schlüssel.
• Der Tagesdeckel eines Schlüssels beginnt um 00:00 UTC neu, der Tagesdeckel des Widgets 86.400 Sekunden nach dem ersten gezählten Aufruf.

Häufige Fragen