Robuste Integrationen verlassen sich auf stabile Konventionen für Statuscodes, opaque IDs, Cursor und Request-Metadaten statt auf zufällige Details einzelner Endpunkte.
HTTP und Statuscodes
Asynchrone Erzeugungen liefern 202 Accepted, solange Arbeit weiterläuft; erfolgreiche Reads 200. Fehler verwenden Problem Details plus stabilen maschinenlesbaren code.
IDs und Zeit
Behandeln Sie file_..., job_..., task_... und project_id als opaque Strings. Zeitstempel sind ISO 8601 UTC; leiten Sie keine Semantik aus der lexikografischen ID-Reihenfolge ab.
Cursor-Pagination
Listen verwenden opaque Cursor. Reichen Sie next_cursor unverändert weiter, behalten Sie Filter bei und erzeugen Sie Cursor niemals clientseitig.
Betriebsheader
Senden Sie Idempotency-Key bei wiederholbaren Creates und speichern Sie X-Request-ID. Beachten Sie Retry-After und RateLimit-* vor Wiederholungen.