Hibák, hívási korlátok, verziózás
A hibaválaszok alakja, mikor érdemes újrapróbálni, a RateLimit fejlécek, és hogyan vezetünk ki egy útvonalat.
Die Form eines Fehlers
Jeder Fehler ist JSON. Es gibt zwei Formen, und der Unterschied ist, woher der Fehler kommt.
| Quelle | Form | Beispiel |
|---|---|---|
| Von Posty, wegen einer Geschäftsregel | Das Feld msg enthält den lesbaren Satz. | { "msg": "No file provided" } |
| Von der Validierung der Anfrage | Die Form des Frameworks: statusCode, message, error. | { "statusCode": 400, "message": [...] } |
Das Schema ApiError im OpenAPI-Dokument beschreibt all das auch maschinenlesbar. Pro Statuscode steht dabei, ob ein erneuter Versuch sinnvoll ist.
Statuscodes
| Code | Was es bedeutet | Typische Ursache |
|---|---|---|
| 400 | Die Anfrage ist ungültig. | Fehlendes Pflichtfeld, falsches Datumsformat, unbekannter Enum-Wert. |
| 401 | Keine gültigen Zugangsdaten. | Fehlender, falscher oder ersetzter Schlüssel; abgelaufenes OAuth-Token. |
| 403 | Nicht genug Berechtigung. | Fehlender Scope, oder der Besitzer des Schlüssels wurde herabgestuft. Die Antwort nennt beides. |
| 404 | Diese Ressource gibt es nicht. | Falsche ID, oder ein Element aus einem anderen Arbeitsbereich. |
| 402 | Der Tarif erlaubt das nicht. | Das Kontingent ist aufgebraucht, oder die Funktion gehört nicht zum Tarif. |
| 429 | Zu viele Anfragen. | Das Aufruflimit ist aufgebraucht. Siehe den Header Retry-After. |
| 5xx | Bei uns ist etwas schiefgelaufen. | Vorübergehend. Ein erneuter Versuch lohnt sich. |
Wann du es erneut versuchen sollst
400, 401, 403 und 404 gehen nicht weg, bis du etwas änderst: Erneut versuchen ist nur Last. 429 und 5xx sind vorübergehend. Dafür ist exponentiell steigende Wartezeit das richtige Verhalten.
Wenn ein Aufruf von POST /posts mit Timeout endet, kannst du eine verlorene Antwort nicht von einer verlorenen Anfrage unterscheiden. Der naheliegende erneute Versuch veröffentlicht einen Beitrag zweimal auf dem echten Konto von jemandem. Schütz den Aufruf mit einem Idempotenzschlüssel, oder frag zuerst den Kalender ab.
Aufruflimits
Jede Antwort trägt diese Header, mit einem eigenen Kontingent je Pfad, je Schlüssel:
| Header | Was er sagt |
|---|---|
RateLimit-Limit | Wie groß das Kontingent im jeweiligen Zeitfenster ist. |
RateLimit-Remaining | Wie viel davon noch übrig ist. |
RateLimit-Reset | In wie vielen Sekunden es zurückgesetzt wird. Sekunden, kein Zeitstempel. |
RateLimit-Policy | Die Beschreibung der geltenden Regel. |
Retry-After | Nur bei 429: wie lange du warten sollst. |
curl -i https://api.posty.hu/public/v1/integrations \
-H "Authorization: psty_a_kulcsod"
RateLimit-Limit: 60
RateLimit-Remaining: 58
RateLimit-Reset: 41
RateLimit-Policy: 60;w=60Wart nicht auf den 429. Am Restwert kannst du schon vorher langsamer werden. Ein geplanter Sync, der den Restwert beobachtet, läuft nie ins Limit.
Versionierung und Abkündigung
Die Version steht im Pfad: Jeder öffentliche Aufruf liegt unter /public/v1. Eine inkompatible Änderung würde als neue Version erscheinen (/public/v2), und v1 hält seinen Vertrag ein.
- Erweiterungen passieren innerhalb von v1: neues optionales Feld, neuer Pfad, neuer Enum-Wert. Deshalb sollte dein Code Felder ignorieren, die er nicht kennt.
- Bei der Abkündigung bekommt die Antwort den Header
Deprecation: true, dazu im HeaderSunsetdas Datum, ab dem sie nicht mehr funktioniert, und einen HeaderLinkmit den Details. - Das Sunset-Datum darf nie weniger als 180 Tage nach dem ersten
Deprecation-Header liegen.
Derzeit wird nichts abgekündigt. Die maschinenlesbare Beschreibung steht immer im OpenAPI-Dokument. Wenn dein Code daraus generiert wird, bekommt er die Erweiterungen von selbst.
Die vollständige Liste der Endpunkte findest du auf der Seite Endpunkte.