Verhalten bei Fehlern und Ausfall

Pendelzeiten sind eine Zusatzinformation. Empfehlung: Wenn die API nicht antwortet oder einen Fehler liefert, blenden Sie die Funktion aus, statt Ihren Nutzern eine Fehlermeldung zu zeigen. Ihre Seite – Stellenliste, Filialsuche – funktioniert dann wie ohne Pendelzeiten weiter.

Fehlerformat

Fehler kommen als Problem Details nach RFC 9457 (Content-Type: application/problem+json):

JSON

{
  "type": "https://api.pendelzeit.de/problems/validation-failed",
  "title": "Ungültige Anfrage",
  "status": 422,
  "detail": "1 Feld ist ungültig.",
  "errors": [ { "pointer": "/destinations", "detail": "Höchstens 100 Ziele erlaubt." } ]
}

Status	Ursache	Was tun
`400`, `422`	Anfrage fehlerhaft	Fehler im Client beheben; `errors[].pointer` zeigt auf das Feld
`401`, `403`	Key fehlt, gesperrt oder nicht für diese Domain/IP	Konfiguration prüfen; Funktion ausblenden
`429`	Limit erreicht	nach `Retry-After` Sekunden erneut versuchen oder ausblenden
`503`	Dienst ausgelastet, eine Engine nicht erreichbar oder (nur bei ÖPNV) kein gültiger Fahrplan	einmal nach `Retry-After` erneut versuchen, sonst ausblenden
`500`	unerwarteter Fehler	ausblenden

Zeitlimit setzen

Eine Anfrage mit 100 Zielen dauert ohne Cache in der Regel unter 2 Sekunden. Setzen Sie ein Zeitlimit (z. B. 5 Sekunden) und blenden Sie die Funktion danach aus.

JavaScript

const API = 'https://api.pendelzeit.de';
const KEY = 'pz_pk_IHR_OEFFENTLICHER_KEY';

// Liefert die Reisezeiten oder null – dann zeigt die Seite einfach keine Pendelzeiten an.
async function travelTimesOrNull(request, timeoutMs = 5000) {
  try {
    const response = await fetch(API + '/v1/travel-times', {
      method: 'POST',
      headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
      body: JSON.stringify(request),
      signal: AbortSignal.timeout(timeoutMs),
    });
    if (response.status === 503 || response.status === 429) {
      console.warn('Pendelzeiten vorübergehend nicht verfügbar, erneut nach', response.headers.get('Retry-After'), 's');
      return null;
    }
    if (!response.ok) {
      console.warn('Pendelzeiten nicht verfügbar:', (await response.json()).title);
      return null;
    }
    return await response.json();
  } catch (error) {
    console.warn('Pendelzeit-API nicht erreichbar:', error.name);
    return null;
  }
}

const result = await travelTimesOrNull({
  origin: { lat: 48.39842, lon: 9.99173 },
  destinations: [{ id: 'a', location: { lat: 48.39265, lon: 10.0106 } }],
  modes: ['walk'],
});
console.log(result ? `${result.results.length} Ergebnis(se)` : 'ausgeblendet');

Status des Dienstes

GET /v1/health (ohne Key) meldet den Zustand der API und der Rechenkerne (ÖPNV, PKW, Adressen). Für ein Monitoring auf Ihrer Seite ist das geeignet; vor jeder Anfrage abzufragen ist nicht nötig.

Shell

curl -sS --fail-with-body 'https://api.pendelzeit.de/v1/health'

status ist ok, degraded (ein Teil nicht erreichbar, z. B. ÖPNV – andere Verkehrsmittel funktionieren) oder down mit Status 503. Ein abgelaufener Fahrplan zählt wie ein ausgefallener ÖPNV. dataVersions nennt den Stand der Daten (Fahrplan, Straßen, Adressen).