Fehlerliste und bekannte API-Fallen

SchemaAnkerlink kopieren

Betroffene FälleAnkerlink kopieren

Website not found bei Website-Monitoring-EndpunktenAnkerlink kopieren

Betroffene Endpunkte:

• GET /api/websites/:websitePublicId/check-history
• GET /api/websites/:websitePublicId/uptime-stats

Früherer Effekt:

{
  "error": true,
  "statusCode": 404,
  "statusMessage": "Website not found",
  "message": "Website not found"
}

Grund:

• Die Route hat nur die alte numerische id direkt geparsed.
• Eine UUID wurde nicht in die interne numerische ID aufgelöst.

Aktueller Stand:

• Public IDs funktionieren jetzt wie in der Doku beschrieben.
• Legacy-Integer-IDs bleiben aus Kompatibilitätsgründen gültig.

Forbidden bei Organisations-Details mit Public IDAnkerlink kopieren

Betroffener Endpoint:

• GET /api/organizations/:organizationPublicId

Grund:

• Die Berechtigungsprüfung lief früher gegen Number(id).
• Bei einer UUID wurde daraus NaN, was zu 403 Forbidden führte.

Aktueller Stand:

• Die Route und die Billing-Routen lösen organizationPublicId jetzt korrekt in die interne ID auf.

ZodError bei optionalen Listen-ParameternAnkerlink kopieren

Betroffene Endpunkte:

• GET /api/customer-ips
• GET /api/customer-domains

Typisches Muster:

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request"
}

Grund:

• Nicht das Weglassen der Parameter war das Problem.
• Das Problem waren leere Query-Werte wie ?page=&perPage=.

Lösung:

• Unbenutzte optionale Parameter weglassen.
• Die API ignoriert für diese Felder jetzt leere Strings robuster.

Monitor-Ownership-FehlercodesAnkerlink kopieren

Seit dem Managed-vs.-Self-Service-Modell können Monitor-Schreib-Endpunkte aller Typen (Website, DNS, ICMP, SMTP, SSH, FTP, IMAP/POP, Domain, DNSBL) diese 403-Codes in data.code liefern:

Monitorkontingent-FehlercodesAnkerlink kopieren

Eine Organisation hat ein Monitorkontingent. Ist es erschöpft, scheitert das Anlegen eines Monitors - oder es hebt die Organisation auf die nächste Kontingentstufe, wenn sie selbst hochstuft. Diese Stufe hat einen höheren Monatspreis, und die Differenz wird für den Rest des laufenden Zeitraums abgerechnet.

Kundenpaket-FehlercodesAnkerlink kopieren

POST /api/customers und PATCH /api/customers/:customerPublicId lösen das Paket eines Kunden auf. Beide weisen ein Paket zurück, das die Organisation nicht hat:

PATCH hat einen unbekannten packageType früher unverändert gespeichert und packageId leer gelassen. Ein solcher Kunde hing an gar keiner Paketkonfiguration, wodurch sich seine Datenaufbewahrung nicht auflösen liess. Sende packageId oder einen packageType, den die Organisation hat.

Fehlercodes fürs Website-PrüfintervallAnkerlink kopieren

checkInterval hat je nach Monitor-Art eine andere Obergrenze, weil der Wert zweierlei bedeutet: bei aktiv getakteten Monitoren ist er die Abfragefrequenz und bleibt bei 1 bis 1440 Minuten (24 Stunden), bei heartbeat-Monitoren ist er das erwartete Ping-Intervall und reicht von 1 bis 43200 Minuten (30 Tage), ein monatlicher Cron-Job ist ein legitimer Monitor.

POST /api/websites meldet dieselbe Obergrenze als Validierungsfehler auf dem Pfad checkInterval statt als data.code, weil die Art dort schon aus dem Request-Body feststeht.

Fehlercodes fürs Ersatzziel (connect target)Ankerlink kopieren

connectHost, connectPort und connectTlsInsecure verbinden die Prüfung mit einem anderen Host als dem aus url, während url, der Host-Header und das TLS-SNI unverändert bleiben - die Semantik von curl --resolve. Sowohl POST /api/websites als auch PATCH /api/websites/:id (Teil-Update eingeschlossen) prüfen sie gleich.

Nicht verfügbar für playwright-Szenarien und heartbeat-Monitore: beide durchlaufen nicht die HTTP/SSL-Prüfkette, in die connectHost eingreift - die Felder werden bei diesen Monitor-Arten angenommen, wirken sich aber nicht aus.

Check-Mode-Fehlercodes (SSH-/SMTP-/FTP-/IMAP-POP-Monitore)Ankerlink kopieren

Die Monitor-Typen mit Zugangsdaten (SSH, SMTP, FTP, IMAP/POP) unterstützen ein Feld checkMode (protocol | tcp, Standard protocol). Im Modus tcp führt der Monitor nur eine reine TCP-Port-Erreichbarkeitsprüfung durch, Zugangsdaten sind weder erforderlich noch werden sie gespeichert. Die Create- und Update-Endpunkte dieser vier Typen können diese 400-Codes in data.code liefern:

Incident-FehlercodesAnkerlink kopieren

Nur manuelle (Statusseiten-)Incidents können gelöscht werden. DELETE /api/incidents/:id liefert diesen data.code:

Fehlercodes für WartungsfensterAnkerlink kopieren

POST /api/maintenance-windows/preview-occurrences (Doku) kann diesen data.code liefern:

Anlegen, Ändern und Löschen eines Fensters (POST /api/maintenance-windows, PATCH /api/maintenance-windows/{id}, DELETE /api/maintenance-windows/{id}) können diese liefern:

Ein wiederholter Anlege-Aufruf ist ungefährlich: ein Fenster, dessen vollständiger Anfragekörper einem bereits vorhandenen entspricht, entsteht kein zweites Mal, das vorhandene kommt zurück, und seine Abonnenten werden nicht ein zweites Mal angekündigt.

Organisationsberichte-FehlercodesAnkerlink kopieren

Endpunkte unter /api/organization/reports und /api/organization/report-runs können diese data.code-Werte liefern:

Datenexport-FehlercodesAnkerlink kopieren

Endpunkte unter /api/organization/data-export (siehe Datenexport anfordern) können diese data.code-Werte liefern:

Agent-Auth-FehlercodesAnkerlink kopieren

Agent-Zugriffstokens (wsma_, siehe Agent-Authentifizierung) sind standardmässig hart auf eine GET/HEAD-Allowlist beschränkt. Ein Token mit Schreib-Scope (api.write.monitors, api.write.incidents) wird stattdessen je Methode und Pfad geprüft, gegen eine feste Positivliste, die heute nur diese beiden Bereiche abdeckt -- alles andere, einschließlich Abrechnung, Zugangsdaten und jeder Pfad auf der gemeinsamen Schreib-Sperrliste, bleibt unabhängig vom Scope unerreichbar. Beide Token-Arten erreichen weiterhin nichts außerhalb ihrer eigenen Lese-Allowlist.

API-Token-FehlercodesAnkerlink kopieren

Ein kundengebundenes API-Token (wsm_ mit customerId) bleibt in seinem Kunden. Organisationsweite Pfade haben keine Kundendimension, das Token erreicht sie deshalb gar nicht: alles unter /api/organizations/**, /api/organization/** (außer GET /api/organization), /api/users/**, /api/admin/**, /api/platform-admin/**, /api/escalation-config/**, /api/custom-pricing, /api/custom-fields/**, /api/im/**, /api/notifications/send-alert, Schreibzugriffe auf /api/package-configs/**, Anlegen und Löschen von Kunden sowie /api/customers/bulk. Kein API-Token, ob kundengebunden oder nicht, kann weitere Tokens erzeugen.

Claim-Flow-FehlercodesAnkerlink kopieren

Die service_auth-Registrierung und die Claim-Zeremonie (siehe Claim-Flow) können zusätzlich zu den obigen Basis-Agent-Auth-Codes diese error-/data.code-Werte liefern:

ID-JAG-FehlercodesAnkerlink kopieren

Registrierungen vom Typ identity_assertion (siehe Identity Assertion (ID-JAG)) können zusätzlich liefern:

Verbundene-Apps-Fehlercodes (OAuth-Verbindungen)Ankerlink kopieren

GET /api/oauth/connections und DELETE /api/oauth/connections/:clientId (siehe Verbundene Apps) können zusätzlich zum Standard-401 unauthorized diese data.code-Werte liefern:

Fehlercodes der OAuth-ZustimmungAnkerlink kopieren

Diese Codes stammen von der Zustimmungsseite, über die jede OAuth-/MCP-Autorisierung jetzt läuft (POST, auf /api/oauth/consent). Wie die Step-up- und die Kontolöschungs-Route ist sie session-gebunden und nicht Teil der öffentlichen API-Oberfläche, und Methode und Pfad stehen hier aus demselben Grund getrennt: eine METHOD /api/...-Routenzeile auf diesen Seiten ist es, was einen Endpunkt in /openapi.json veröffentlicht. Sie stehen hier, weil die Codes das sind, worüber die Seite und jede Supportanfrage sprechen. Der Scope-Katalog selbst steht unter Verbundene Apps.

Die Prüfungen laufen in der Reihenfolge unten, du bekommst also den Code der ersten, die fällt. Die letzte Zeile ist die Ausnahme: sie kommt von Better Auth, nachdem jede Prüfung dieser Liste bestanden ist.

Fehlercodes für Status-Seiten-AbonnentenAnkerlink kopieren

Die Endpunkte zum Auflisten, Löschen und Exportieren von Status-Seiten-Abonnenten können zusätzlich zum Standard-401 unauthorized und dem zweistufigen statusPageNotFound-Verhalten (auf jeder Seite beschrieben: eine fehlerhafte oder unbekannte :id ist ein code-loses 400/404 aus der Public-ID-Auflösung; nur eine :id, die sich auflöst, aber an der Organisations-/Kunden-Scope-Prüfung scheitert, trägt data.code: statusPageNotFound) diese data.code-Werte liefern:

Public IDs in DNS- und DNSBL-MonitorenAnkerlink kopieren

Die folgenden Pfad-Endpunkte können in den Docs und in Clients mit Public IDs verwendet werden:

• GET /api/customer-domains/:customerDomainPublicId
• PATCH /api/customer-domains/:customerDomainPublicId
• DELETE /api/customer-domains/:customerDomainPublicId
• GET /api/customer-ips/:customerIpPublicId
• PATCH /api/customer-ips/:customerIpPublicId
• DELETE /api/customer-ips/:customerIpPublicId

Legacy-Integer-IDs bleiben auch dort weiterhin kompatibel, die Public ID ist aber die bevorzugte Form für Integrationen und Postman-Collections.

Incident-Management-(IM)-API-FehlercodesAnkerlink kopieren

Die öffentliche Incident-Management-API (POST /api/im/events, GET/POST /api/im/incidents/**, GET /api/im/teams, GET/POST /api/im/schedules/**, GET /api/im/on-call) erfordert einen organisationsweiten API-Token und kann diese data.code-Werte liefern:

GET /api/im/incidents, Incident erstellen, die Status-/Resolve-Endpunkte, Schedules erstellen und Schedule-Overrides hinzufügen können außerdem den generischen 400 invalidRequestBody bei fehlerhafter Eingabe liefern (z. B. ein unbekannter status-Filterwert, eine nicht-ganzzahlige :id, eine fehlende oder fehlerhafte Rotationsschicht). POST /api/im/events kann zusätzlich 429 Too Many Requests liefern (600 Anfragen/Minute pro Organisation, mit einem retryAfter-Feld, aber ohne data.code), oder 503 mit data.code: unavailable, wenn das Event nicht eingereiht werden konnte, sicher wiederholbar.

Nutzerverwaltungs-FehlercodesAnkerlink kopieren

PATCH /api/users/:id (Doku) und DELETE /api/users/:id (Doku) schützen die Organisation davor, sich selbst auszusperren:

Etiketten-FehlercodesAnkerlink kopieren

POST /api/tags hält in created_by fest, welcher Mensch ein Etikett angelegt hat. Diese Spalte ist NOT NULL und trägt keinen Fremdschlüssel. Ein Aufruf über eine Agenten-Sitzung (eine MCP-Verbindung, create_tag) wird deshalb abgewiesen, statt einen Ersatzwert zu bekommen: irgendetwas dort hineinzuschreiben würde den Zweig „der Urheber darf ändern“ der Rechteprüfung still und dauerhaft kaputt machen.

Die übrige Etikettenfläche (POST /api/tags, PATCH /api/tags/{id}, DELETE /api/tags/{id} sowie Anhängen und Abnehmen mit POST /api/monitor-tags und DELETE /api/monitor-tags) kann diese liefern:

Das Anhängen ist wiederholbar: ein Etikett, das schon am Monitor hängt, wird kein zweites Mal angehängt, und der Aufruf gelingt trotzdem.

Fehlercodes für ÄnderungswünscheAnkerlink kopieren

POST /api/monitors/:type/:id/change-requests und die ältere, nur für Websites gedachte Route unter /api/websites/:id/change-requests halten den anfragenden Menschen in requested_by fest, einer NOT NULL-Spalte mit Fremdschlüssel auf user. Ein Aufruf über eine Agenten-Sitzung wird deshalb abgewiesen statt mit einem Ersatzwert versehen:

Benachrichtigungskanal-FehlercodesAnkerlink kopieren

Ein Matrix-Kanal ist ein Sonderfall, den man kennen sollte: seine homeserverUrl wird beim Speichern auf ihre Form geprüft und bei der Zustellung noch einmal aufgelöst. Ein Homeserver, der nur auf eine private oder reservierte Adresse auflöst, wird bei der Zustellung abgewiesen, und die Abweisung steht an diesem Alarm, nicht als Fehler an diesem Endpunkt.

Fehlercodes für eigene DomainsAnkerlink kopieren

Die Verify- und Activate-Endpunkte der White-Label-Domains und der Statusseiten-Domains beanspruchen einen Hostnamen für deine Organisation. Seit dem 04.09.2026 ist ein Hostname nur unter beanspruchten Einträgen (verified/active) eindeutig; ein pending-Eintrag blockiert niemanden und verfällt nach 7 Tagen.

404 für Ressourcen außerhalb des ScopesAnkerlink kopieren

Seit dem 04.09.2026 antwortet jeder Ressourcen-Endpunkt mit 404 und seinem üblichen Not-found-Code (websiteNotFound, monitorNotFound, customerNotFound, customerDomainNotFound, customerIpNotFound, statusPageNotFound), sowohl wenn die Ressource nicht existiert als auch wenn sie existiert, aber nicht in deiner Organisation oder deinem Kundenscope liegt. Ein 403 bleibt rollenbasierten Ablehnungen vorbehalten (falsche Rolle, kundengebundenes Token auf einem Organisationspfad). Tests, die für „gehört einem anderen Kunden“ ein 403 erwarteten, müssen angepasst werden.

Fehlercodes für Rate-Limits und GrößenAnkerlink kopieren

POST /api/organizations/:id/vat-id/validate ist auf 10 Prüfungen pro Stunde und Organisation begrenzt (429 mit data.retryAfter). POST /api/im/sources/:id/test-alert wendet jetzt dieselben Body-Grenzen an wie die Ingest-URL (payloadTooLarge, invalidJson, payloadTooDeep).

Fehlercodes für Webhook- und SMTP-ZieleAnkerlink kopieren

Organisation gesperrt oder gelöschtAnkerlink kopieren

Ein Gate vor dem Kontozustand-Gate weiter unten sperrt jede /api/*-Anfrage, Sitzung, wsm_-API-Token oder wsma_-Agenten-Token gleichermaßen, anhand des Organisationsstatus. Plattform-Admins und -Supporter sind ausgenommen, wie überall sonst auch.

Eine suspended (gesperrte) Organisation bekommt 423 Organization suspended ohne data.code, außer für eine schmale Freigabeliste, die erreichbar bleibt, damit sie sich zurückzahlen kann: die Organisation lesen, das Kontingent ändern, die Datenexport-Endpunkte oben, die Tenant-Abfrage sowie die Mollie-Mandat-Rückkehr/-Reconcile- und Rabattcode-Route. Jede andere Route ist gesperrt.

Eine deleted (gelöschte) Organisation bekommt diese Freigabeliste NICHT und verliert zusätzlich zwei Routen, die bei suspended noch offen bleiben: Abmelden (POST auf /api/auth/sign-out) und beide Sitzungs-Bootstrap-Abfragen (GET auf /api/auth/get-session und /api/_internal/auth/get-session) antworten ebenfalls mit 423 Organization deleted und data.code organizationSuspended, bewusst, denn Abmelden löscht die Sitzungszeile aus Redis, und genau diese Zeile ist Beweismittel für die Löschprüfung. Vor dem 15.09.2026 erreichten Sitzung, API-Token und Agenten-Token einer gelöschten Organisation unverändert jede Route, genau die Lücke, die das schließt. „Gelöscht“ heißt hier status = 'deleted' ODER der dauerhafte Marker deletion_completed_at ist gesetzt. Maßgeblich ist, ob die Löschung abgeschlossen ist; der angezeigte Status der Organisation ist dafür nicht entscheidend. Zwei weitere Flächen folgen derselben Regel: /mcp weist API-Tokens und OAuth-Verbindungen einer gelöschten Organisation mit 423 ab, bevor ein Server aufgebaut wird, und eine Passwort-Reset-Mail wird nicht verschickt; der Endpunkt antwortet genau wie bei einer unbekannten Adresse. Eine gekündigte Organisation in ihrer Karenzzeit ist von diesem Gate nur unbetroffen, solange ihre Löschung noch nicht abgeschlossen ist. Diese Sperre greift innerhalb weniger Sekunden statt augenblicklich, weil der Kontozustand dahinter kurz zwischengespeichert wird.

Kontozustand an den Auth-EndpunktenAnkerlink kopieren

Better Auths eigene Routen (/api/auth/**, etwa change-password, update-user, two-factor/*, mcp/token-Refresh) weisen ein deaktiviertes Konto oder eine gesperrte Organisation genauso ab wie die API. Sign-in, Sign-out, Passwort-Reset, E-Mail-Verifikation und get-session bleiben erreichbar. Bei einer gelöschten Organisation ist die Liste enger: nur Sign-in, Registrierung, Passwort-Reset und E-Mail-Verifikation bleiben erreichbar, sign-out und get-session antworten wie oben mit 423, und eine neue Anmeldung scheitert ohnehin nach der Zugangsdatenprüfung, weil die Sitzungsanlage selbst abweist.

MFA-FehlercodesAnkerlink kopieren

Diese Fehlercodes gehören zur Zwei-Schritt-Bestätigung (MFA) und können von ansonsten unabhängigen Endpunkten geliefert werden, sobald das jeweilige Gate greift:

Diese Codes stehen als data.code-Wert im JSON-Fehlerbody, zusätzlich zum jeweils genannten HTTP-Status.

Fehlercodes der KontolöschungAnkerlink kopieren

Diese Codes stammen aus der Kontolöschung in der App (GET, POST und DELETE, auf /api/account/deletion-request). Wie der Step-up-Endpunkt oben sind diese Routen session-gebunden und nicht Teil der öffentlichen API, sie stehen hier, weil die Codes das sind, worüber die App und jede Supportanfrage sprechen.

Eine Löschung wird angefordert, nicht sofort vollzogen: die Anforderung setzt einen Termin 30 Tage in der Zukunft und ist bis dahin widerrufbar. Die Administratoren der Organisation werden über die Anforderung und über den Widerruf benachrichtigt, sie sind es, die eine Bereitschaftsrotation nachbesetzen können, die der Weggang offen ließe.

USt-IdNr.-Validierung: FehlercodesAnkerlink kopieren

POST /api/organizations/:organizationPublicId/vat-id/validate (siehe USt-IdNr. validieren) kann zusätzlich zu den Standard-Codes 401 unauthorized, 403 forbidden und 404 organizationNotFound diese data.code-Werte liefern:

Update Billing Details: benötigter BodyAnkerlink kopieren

Endpoint:

• PATCH /api/organizations/:organizationPublicId/billing

Aktuell unterstützter Request-Body:

{
  "billingEmail": "billing@deinkunde.com"
}

Der Endpoint akzeptiert derzeit nur billingEmail.