Fehlerbehandlung

Alle Fehler-Responses verwenden ein einheitliches JSON-Format – unabhängig vom Accept-Header, den du mitschickst. Der Body enthält nie interne Details wie Klassennamen, Pfade oder einen Stacktrace.

{
  "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_grant	Nur am Token-Endpoint: Der Besitzer-Benutzer des API-Zugangs ist deaktiviert (error_description: The user of this client is disabled or deleted.)
400	unauthorized_client	Nur am Token-Endpoint: Der API-Zugang wurde widerrufen, z.B. weil sein Besitzer-Benutzer gelöscht wurde (error_description: The grant type is unauthorized for this client_id)
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
401	invalid_client	Der Besitzer-Benutzer des API-Zugangs ist deaktiviert (error_description: The user of this OAuth client is disabled or deleted.)
403	client_revoked	OAuth-Client wurde widerrufen
403	access_denied	Der Endpunkt steht nur Offisy Connect Geräten zur Verfügung
403	access_denied	Der Besitzer-Benutzer deines API-Zugangs hat nicht die benötigte Berechtigung (Standard-error_description: Insufficient permission for this resource.)
403	insufficient_scope	Der Client hat nicht die benötigte Berechtigung
404	not_found	Ressource nicht gefunden. Beim Einzelabruf einer Rechnung, Honorarnote, Bareinnahme oder Mahnung, die für den Besitzer-Benutzer nicht erreichbar ist (Mandant ohne Zugriff), ist die Antwort exakt dieselbe wie bei einer unbekannten UUID: The requested resource was not found.
405	method_not_allowed	Die HTTP-Methode wird für diesen Endpoint nicht unterstützt. Die Response enthält einen Allow-Header mit den erlaubten Methoden
429	rate_limit_exceeded	Zu viele Anfragen. Warte und versuche es erneut.
andere 4xx	invalid_request	Sammelcode für 4xx-Fehler ohne eigenen Code
5xx	server_error	Interner Serverfehler. Die error_description nennt keine Details

Hinweis zu Query-Parametern: Ein Query-Parameter, der als Array statt als Einzelwert übergeben wird (?statusUuid[]=a&statusUuid[]=b), ergibt an allen OAuth-Endpoints 400 validation_error. Das Gleiche gilt für ungültiges UTF-8. Es gibt in diesen Fällen keine generische HTML-Fehlerseite.

Hinweis: Bei 429 enthält die Response einen Retry-After Header mit der Wartezeit in Sekunden. Bei Überschreiten des Unternehmensbudgets enthält der Response-Body zusätzlich plan und limit – anhand dieser Kombination liest du ab, ob das Minuten- oder das Tageslimit gegriffen hat. Beim IP-Limit für ungültige Tokens enthält der Body nur error und error_description. 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.

Deaktivierter oder gelöschter Besitzer

Ein API-Zugang funktioniert nur, solange sein Besitzer-Benutzer aktiv ist.

• Deaktivierter Besitzer: Die Resource-API antwortet mit 401 invalid_client (The user of this OAuth client is disabled or deleted.), der Token-Endpoint mit 400 invalid_grant. Wird der Benutzer wieder aktiviert, funktioniert der API-Zugang ohne weiteres Zutun wieder.
• Gelöschter Besitzer: Beim Löschen des Benutzers werden seine API-Zugänge widerrufen. Die Resource-API antwortet danach dauerhaft mit 403 client_revoked (OAuth client has been revoked.), auch mit einem abgelaufenen Access Token. Der Token-Endpoint antwortet mit 400 unauthorized_client (The grant type is unauthorized for this client_id). Ein widerrufener API-Zugang lässt sich nicht wiederherstellen.
• Beendete Kooperation: Ein API-Zugang, dessen Besitzer bei einem Kooperationspartner arbeitet, verliert mit dem Ende der Kooperation seine Rechte im fremden Unternehmen. Die API-Zugänge werden dabei nicht widerrufen, die Anfragen antworten mit 403 access_denied.

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`);
  }
}