Fehler, Paginierung & Idempotenz

Das einheitliche Fehlerformat samt Codes, Cursor-Paginierung und sichere Wiederholungen.

Fehlerformat

Jede Fehlerantwort hat dieselbe Form. code ist der stabile, maschinenlesbare Vertrag; message ist ein Hinweis für Menschen; details gibt es bei Validierungsfehlern.

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": { "idea": "Required" }
  }
}

Fehlercodes

Code	HTTP	Bedeutung
`unauthorized`	401	Fehlender, ungültiger, widerrufener oder inaktiver Key.
`forbidden`	403	Reserviert; die Trennung zeigt sich stattdessen als 404.
`not_found`	404	Ressource fehlt oder gehört nicht dir.
`validation_error`	422	Body oder Query hat die Validierung nicht bestanden (siehe details).
`unprocessable`	422	Formal korrekte, aber inhaltlich ungültige Anfrage.
`conflict`	409	Widerspricht dem aktuellen Zustand (z. B. bereits veröffentlicht).
`rate_limited`	429	Kontingent erschöpft; zurückfahren und erneut versuchen.
`internal_error`	500	Unerwarteter Serverfehler. Es werden keine Details preisgegeben.

Paginierung

Listen-Endpunkte nutzen eine undurchsichtige Cursor-Paginierung, neueste zuerst. Übergib ?limit= (1–100, Standard 20) und das page.next_cursor der vorherigen Seite als ?cursor=. Ist next_cursor null, bist du am Ende.

{
  "data": [ { "id": "9b1c...", "status": "published" } ],
  "page": {
    "next_cursor": "MjAyNi0wNi0xNlQwODowMDowMFp8OWIxYw==",
    "has_more": true
  }
}

curl "https://app.tidefall.de/api/v1/posts?limit=50&cursor=MjAyN..." \
  -H "Authorization: Bearer lps_YOUR_KEY"

Idempotenz

Sende bei erzeugenden bzw. veröffentlichenden POST-Aufrufen einen Idempotency-Key-Header, damit eine wiederholte Anfrage genau einmal verarbeitet wird. Die Antwort der ersten Anfrage wird 24 Stunden gespeichert; eine Wiederholung mit demselben Key liefert die ursprüngliche Antwort mit Idempotency-Replayed: true.

curl -X POST https://app.tidefall.de/api/v1/posts \
  -H "Authorization: Bearer lps_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{ "idea": "Why most ERP migrations fail" }'

Nimm pro logischer Operation eine neue UUID. Wird ein Key mit anderem Body wiederverwendet, kommt trotzdem die ursprünglich gespeicherte Antwort — ordne also jedem Key genau eine beabsichtigte Aktion zu.