Fehler und Rate-Limits

Beta Die REST-API ist in der Beta. Endpunkte und Felder können sich bis zur Version 1.0.0 noch ändern.

Fehlerformat

Bei einem Fehler antwortet die API mit einem passenden HTTP-Status und immer mit derselben JSON-Form:

Fehlerantwort

{
  "error": {
    "code": "validation_error",
    "message": "Ungültige Abfrageparameter",
    "details": [
      {"path": "from", "message": "Erwartet ein Datum im Format YYYY-MM-DD"}
    ]
  }
}

• code ist ein fester Fehlercode. Werte in deinem Programm diesen Code aus.
• message ist eine deutsche Beschreibung für Menschen. Der Text kann sich ändern; verlasse dich nicht auf ihn.
• details ist optional und enthält zusätzliche Angaben, etwa die fehlerhaften Parameter bei validation_error oder den fehlenden Scope bei forbidden_scope.

Gib bei Rückfragen an den Support die X-Request-Id aus dem Antwort-Header an. Bei Daten-Endpunkten lässt sich damit der protokollierte Request eindeutig zuordnen. Antworten auf unbekannte Pfade (404) und andere HTTP-Methoden (405) haben ebenfalls eine Request-ID, werden aber nicht protokolliert. GET /api/v1/openapi.json liefert keine Request-ID. Sende niemals deinen API-Key mit.

Fehlercodes

HTTP-Status	Code	Bedeutung	Was du tun kannst
400	validation_error	Ein Parameter fehlt, ist falsch geschrieben oder hat ein ungültiges Format, der Zeitraum ist zu lang oder to liegt vor from. In details stehen bei fehlerhaften Parametern deren Name (path) und der Grund (message).	Request anhand der Endpunkt-Beschreibung korrigieren
401	unauthorized	Der API-Key fehlt, ist ungültig oder wurde widerrufen.	Header Authorization: Bearer tmk_live_… prüfen, ggf. neuen Key anlegen
403	forbidden_scope	Dem Key fehlt der Scope für diesen Endpunkt; details.requiredScope nennt ihn.	Key mit passender Berechtigung anlegen
403	license_required	Der Standort hat weder TimeMonkey Pro noch eine laufende Testphase.	TimeMonkey Pro lizenzieren
403	payment_locked	Der Zugang ist wegen einer offenen Zahlung gesperrt.	Offene Rechnung in TimeMonkey begleichen
403	company_pending_review	Der Standort wird gerade vom TimeMonkey-Team geprüft.	An den Support wenden
404	not_found	Der Pfad existiert nicht oder der angefragte Mitarbeiter wurde nicht gefunden.	Pfad bzw. ID prüfen
405	method_not_allowed	Es wurde eine andere Methode als GET verwendet. Die Antwort enthält den Header Allow: GET.	Nur GET verwenden
429	rate_limited	Das Limit pro Minute oder pro Tag ist erreicht.	Bis zum Ablauf von Retry-After warten
500	internal	Unerwarteter Fehler auf Seiten von TimeMonkey.	Später erneut versuchen; bei wiederholtem Auftreten mit X-Request-Id an den Support wenden

Welche Voraussetzung in welcher Reihenfolge geprüft wird, steht unter Zugangsvoraussetzungen.

Rate-Limits

Damit die API für alle schnell bleibt, gelten pro API-Key zwei Limits:

Zeitfenster	Limit
Kalenderminute	60 Requests
Kalendertag (Europe/Berlin)	1.000 Requests

• Die Fenster sind feste Kalenderfenster: Das Minutenlimit beginnt mit jeder vollen Minute neu, das Tageslimit um Mitternacht deutscher Zeit.
• Ist ein Limit erreicht, antwortet die API mit 429 rate_limited. Der Header Retry-After nennt die Sekunden bis zum Ende des überschrittenen Fensters.
• Requests, die schon an der Prüfung von API-Key, Lizenz oder Scope scheitern (401 oder 403), zählen nicht für die Limits. Requests mit ungültigen Parametern (400) zählen dagegen mit.
• Ein Request, der am Minutenlimit scheitert, verbraucht kein Tageskontingent.
• Die Limits gelten je Key. Nutzen mehrere Systeme die API, gib jedem einen eigenen Key.

429 Too Many Requests (Header Retry-After: 23)

{
  "error": {
    "code": "rate_limited",
    "message": "Limit von 60 Requests pro Minute erreicht"
  }
}

Limits einhalten

• Hole Listen mit limit=500 ab, um möglichst wenige Seiten abzurufen.
• Frage nur die Zeiträume ab, die sich geändert haben könnten, statt regelmäßig alles neu zu laden.
• Warte bei 429 die in Retry-After genannten Sekunden ab und wiederhole den Request dann. Wiederhole Requests mit 4xx-Fehlern sonst nicht unverändert – sie schlagen erneut fehl.
• Die Auswertungs-Endpunkte können Seiten mit weniger Einträgen als limit liefern. Folge nextCursor, statt mit einem höheren limit neu anzufragen.

JavaScript

retry.mjs

async function getWithRetry(url, headers, attempts = 3) {
  for (let attempt = 1; ; attempt++) {
    const response = await fetch(url, {headers});
    if (response.status !== 429 || attempt === attempts) return response;
    const seconds = Number(response.headers.get('Retry-After') ?? '60');
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
}

Python

retry.py

import time

import requests


def get_with_retry(url, headers, params=None, attempts=3):
    for attempt in range(1, attempts + 1):
        response = requests.get(url, headers=headers, params=params, timeout=30)
        if response.status_code != 429 or attempt == attempts:
            return response
        time.sleep(int(response.headers.get("Retry-After", "60")))

Faire Nutzung

Die REST-API ist dafür gedacht, die Daten deines Standorts regelmäßig mit deinen eigenen Systemen abzugleichen, zum Beispiel einmal täglich oder einmal pro Woche. Damit sie für alle Standorte zuverlässig und schnell bleibt, bitten wir dich um eine maßvolle Nutzung:

• Nur abrufen, was du brauchst. Frage die Zeiträume und Mitarbeiter ab, die sich seit dem letzten Abgleich geändert haben können, und speichere die Ergebnisse bei dir, statt dieselben Daten immer wieder neu zu laden.
• Auswertungen sparsam abrufen. Tages-, Monats- und Jahresauswertung berechnet TimeMonkey bei jedem Abruf vollständig neu. Sie sind deutlich aufwendiger als die übrigen Endpunkte. Für einen wöchentlichen Abgleich genügt meist die Monatsauswertung des laufenden Monats.
• Abrufe verteilen. Plane regelmäßige Abgleiche möglichst außerhalb der Hauptarbeitszeit und rufe größere Datenmengen nacheinander statt parallel ab.

Die Rate-Limits sind eine technische Obergrenze zum Schutz vor Lastspitzen, kein Richtwert für die übliche Nutzung.

Übermäßige oder missbräuchliche Nutzung

Die REST-API ist in TimeMonkey Pro für den üblichen Datenabgleich eines Standorts enthalten. Wir behalten uns vor, eine missbräuchliche oder übermäßige Nutzung, die deutlich darüber hinausgeht, gesondert in Rechnung zu stellen. Erwartest du einen höheren Bedarf, etwa häufige Abrufe oder sehr viele Mitarbeiter, sprich uns bitte vorher über den Support an – dann finden wir gemeinsam eine passende Lösung.