Fehler, Statuscodes und Limits

Gilt ab Work7 0.2.0 · Stand 12.09.2026

Fehlerformat

Alle Fehler der Public API haben dieselbe Form:

{
  "error": "insufficient_scope",
  "message": "Scope rapport:read fehlt.",
  "details": { "required": "rapport:read", "scopes": ["core:read"] }
}

HTTP	error	Bedeutung	Was tun
400	validation_error	Pflichtfeld fehlt oder Wert ungültig	message lesen, Eingabe korrigieren
401	unauthorized	Schlüssel fehlt, ungültig oder widerrufen	Header prüfen, ggf. neuen Schlüssel anlegen
403	insufficient_scope	Schlüssel hat den Scope nicht	Scope beim Anlegen des Schlüssels ergänzen
403	module_disabled	Bereich für den Betrieb nicht freigeschaltet	Betrieb muss das Modul buchen; Daten bleiben erhalten
404	NOT_FOUND	Datensatz existiert nicht oder gehört einem anderen Betrieb	ID prüfen
409	CONFLICT	Zustandskonflikt, zum Beispiel Statuswechsel nicht erlaubt	details.code auswerten
429	rate_limited	Zu viele Anfragen	Retry-After (Sekunden) abwarten
500	INTERNAL_ERROR	Unerwarteter Fehler	erneut versuchen, bei Wiederholung melden

Fehler aus der Geschäftslogik (Validierung, Konflikte, nicht gefunden) nutzen dieselben Codes wie die Web-App und tragen zusätzlich code und timestamp.

Rate-Limit

600 Anfragen pro Minute je Schlüssel. Bei Überschreitung antwortet die API mit 429 und dem Header Retry-After. Für Massenabgleiche: Listen mit limit=200 holen, statt Einzelobjekte in Schleifen zu laden.

Pagination

Listen liefern data und pagination:

{
  "data": [ { "id": 1 } ],
  "pagination": { "limit": 50, "offset": 0, "total": 137, "hasMore": true }
}

• limit maximal 200, Standard 50.
• Nächste Seite: offset = offset + limit, solange hasMore wahr ist.
• /time-entries verwendet page und pageSize (maximal 100) und liefert pageInfo im data-Objekt.

Datumsformate

• Zeitstempel: ISO 8601 mit Zeitzone, zum Beispiel 2026-09-12T10:00:00+02:00.
• Tagesdaten (from, to, Termine): YYYY-MM-DD, interpretiert in Europe/Vienna.

Versionierung

Der Pfad trägt die Hauptversion (/api/v1). Innerhalb von v1 kommen Felder und Endpunkte hinzu, bestehende Felder werden nicht entfernt oder umbenannt. Änderungen stehen im technischen Changelog.

Support

Fragen zur Integration: office@work7.net. Bitte Betrieb, Schlüssel-Prefix (w7_live_<prefix>_…) und den Wert des Antwort-Headers x-request-id mitschicken, nie den vollständigen Schlüssel.