Grenzen, Seiten und Fehler der Schnittstelle
Abfragegrenzen einhalten und Fehlerantworten richtig behandeln.
Die Schnittstelle verhält sich vorhersehbar: klare Grenzen, sprechende Fehlercodes und einheitliche Seitenverwaltung. Wer diese Regeln kennt, baut eine Integration, die auch unter Last stabil bleibt.
Für wen
Entwicklerinnen und Entwickler.
Voraussetzungen
Bestehender API-Zugang
Grenzen
- Anfragen — Pro Schlüssel gilt ein Minutenlimit. Die verbleibende Zahl steht in den Antwortkopfzeilen.
- Seitengröße — Standard 50, maximal 200 Datensätze je Seite.
- Seitenverwaltung — Cursorbasiert; die nächste Seite wird über den zurückgegebenen Cursor geholt.
- Zeitraum — Abfragen über sehr lange Zeiträume werden abgelehnt; teilen Sie sie auf.
Fehlercodes
- 400 — Anfrage fehlerhaft — Feld und Grund stehen in der Antwort.
- 401 — Schlüssel fehlt, abgelaufen oder widerrufen.
- 403 — Schlüssel gültig, aber ohne Berechtigung für diese Ressource.
- 404 — Objekt existiert nicht oder liegt außerhalb Ihres Geltungsbereichs.
- 409 — Konflikt, etwa Änderung an einem gesperrten freigegebenen Stand.
- 429 — Limit erreicht; die Kopfzeile Retry-After nennt die Wartezeit.
- 5xx — Fehler auf unserer Seite; mit wachsendem Abstand erneut versuchen.
Jede Fehlerantwort enthält eine Vorgangs-ID. Nennen Sie diese im Ticket — damit ist der Fall in den Protokollen sofort auffindbar.
Schritt für Schritt
- 1
Beschreibung laden
Die OpenAPI-Beschreibung unter /openapi.json listet alle Ressourcen und Felder.
- 2
Seiten durchlaufen
Listen werden über einen Cursor geblättert; verwenden Sie den zurückgegebenen Zeiger statt Seitenzahlen.
- 3
Grenzen beachten
Bei Überschreitung antwortet elyph mit Status 429 und einem Hinweis, wie lange zu warten ist.
- 4
Fehler auswerten
Fehlerantworten enthalten Code, Klartext und, wo sinnvoll, das betroffene Feld.
Ergebnis
Ihre Integration läuft stabil, auch bei Lastspitzen.
Häufige Stolpersteine
- Bei 429 sofort erneut anfragen: Warten Sie die genannte Zeit ab.
Häufige Fragen
- Wie gehen wir mit 429 um?
- Retry-After beachten und exponentiell zurückstufen. Sinnvoller ist meist, weniger häufig abzufragen und stattdessen Webhooks zu nutzen.