Fehlerbehandlung

Alle Fehler-Responses verwenden ein einheitliches JSON-Format.

{
  "error": "error_code",
  "error_description": "Beschreibung des Fehlers"
}

HTTP Status Codes

HTTP Status	Error Code	Beschreibung
400	validation_error	Ungültige Request-Daten (fehlende Felder, falsches Format)
400	invalid_request	Der Access Token wurde nicht im Authorization-Header übertragen, oder auf mehr als einem Weg gleichzeitig
401	invalid_client	Ungültiger oder fehlender Access Token
403	client_revoked	OAuth-Client wurde widerrufen
403	access_denied	Der Endpunkt steht nur Offisy Connect Geräten zur Verfügung
403	insufficient_scope	Der Client hat nicht die benötigte Berechtigung
404	not_found	Ressource nicht gefunden
429	rate_limit_exceeded	Zu viele Anfragen. Warte und versuche es erneut.

Hinweis: Bei 429 enthält die Response einen Retry-After Header mit der Wartezeit in Sekunden. Der Response-Body enthält zusätzlich plan und limit – anhand dieser Kombination liest du ab, ob das Minuten- oder das Tageslimit gegriffen hat. Details und die vollständige Limit-Tabelle findest du unter Rate Limits.

Am Token-Endpoint (POST /api/oauth/v2/token) enthält eine 429-Antwort zusätzlich ein Feld reason mit den Werten company_minute, client_attempts oder ip.

Fehler behandeln

JavaScript

const response = await fetch('https://my.offisy.at/api/oauth/v2/resource/appointments', {
  headers: { 'Authorization': 'Bearer {access_token}' }
});

// Diese drei Header stehen an jeder Antwort, auch bei Erfolg
const limit = response.headers.get('X-RateLimit-Limit');
const remaining = response.headers.get('X-RateLimit-Remaining');
const reset = response.headers.get('X-RateLimit-Reset');

if (!response.ok) {
  const error = await response.json();
  console.error(`${error.error}: ${error.error_description}`);

  if (response.status === 429) {
    console.log(`Plan: ${error.plan}, Limit: ${error.limit}`);

    const retryAfter = response.headers.get('Retry-After');
    console.log(`Retry after ${retryAfter} seconds`);
  }
}