Fehlerliste und bekannte API-Fallen

Diese Seite dokumentiert reale Fehlerbilder, die bei Integrationen aufgetreten sind.

Schema

Error Code	Grund	Lösung / Bug
`404 Website not found`	Einige Website-Unterendpunkte haben früher nur die alte numerische Website-ID akzeptiert, obwohl die Docs `websitePublicId` gezeigt haben.	Behoben. `GET /api/websites/:websitePublicId/check-history` und `GET /api/websites/:websitePublicId/uptime-stats` akzeptieren jetzt Public IDs und weiterhin Legacy-IDs.
`403 Forbidden` auf `GET /api/organizations/:organizationPublicId`	Die Route hat die Pfad-ID früher direkt als Zahl interpretiert. Eine UUID wurde dadurch schon in der Berechtigungsprüfung verworfen.	Behoben. Die Organisations-Detail- und Billing-Routen lösen jetzt `publicId` korrekt auf.
`400 Bad Request` mit `ZodError` bei `customer-ips` oder `customer-domains`	Query-Parameter wie `organizationId=`, `page=` oder `perPage=` wurden als leere Strings gesendet. Zod coerct leere Strings zu `0`, was dann an den Mindestwerten scheitert.	Behoben für `organizationId`, `page` und `perPage`. Optional bedeutet trotzdem: ungenutzte Parameter komplett weglassen statt leere Strings zu senden.

Betroffene Fälle

Website not found bei Website-Monitoring-Endpunkten

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 ID

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-Parametern

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-Fehlercodes

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:

Code	Bedeutung
`managed_by_organization`	Ein kunden-gescopter Aufrufer wollte einen `managed`-Monitor ohne die `canEditManaged`-Ausnahme bearbeiten/löschen. Stattdessen einen Change Request eröffnen.
`selfServiceNotAllowed`	Ein kunden-gescopter Aufrufer wollte einen Monitor anlegen, aber das aufgelöste `allowSelfService` des Kunden ist false.
`selfServiceQuotaReached`	Das Anlegen (oder Umstellen auf) eines `self_service`-Monitors würde `maxSelfServiceUrls` des Kunden überschreiten: das Kontingent zählt alle Monitor-Typen zusammen.
`managementTypeOrgOnly`	Ein Nicht-Org-Admin wollte den `managementType` eines Monitors ändern. Klassen-Wechsel sind Organisations-Admins vorbehalten.
`tooManyOpenRequests`	(`429`) Der Kunde hat bereits 10 offene Change Requests.

Kundenpaket-Fehlercodes

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:

Code	Bedeutung
`invalidPackageType`	(`400`) Die `packageId` gehört nicht zu dieser Organisation, oder der Legacy-`packageType` passte weder auf einen konfigurierten Paketschlüssel noch auf einen Paket-Anzeigenamen dieser Organisation.

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.

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

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:

Code	Bedeutung
`portRequiredForTcp`	IMAP/POP Create oder Update: `checkMode` ist (oder ergibt sich zu) `tcp`, aber es ist weder im Request noch bereits am Monitor gespeichert ein `port` vorhanden. Nur IMAP/POP benötigt für den Modus `tcp` einen expliziten `port`. SSH, SMTP und FTP nutzen dafür ihren protokollspezifischen Default-Port.
`invalidCheckMode`	Nur bei Update-Endpunkten (`PATCH`): `checkMode` wurde übergeben, ist aber weder `protocol` noch `tcp`.

Incident-Fehlercodes

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

Code	Bedeutung
`notManualIncident`	(`403`) Der Incident wurde vom Monitoring erzeugt. Nur von einem Admin erstellte manuelle Incidents können gelöscht werden; automatische Incidents gehören den Workern und sind über die API niemals löschbar.

Fehlercodes für Wartungsfenster

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

Code	Bedeutung
`invalidWindow`	(`400`) `endTime` liegt nicht nach `startTime`.

Organisationsberichte-Fehlercodes

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

Code	Bedeutung
`invalidReportSchedule`	Wöchentlicher Bericht ohne `weekday` oder monatlicher Bericht ohne `dayOfMonth` (1-28).
`invalidReportScope`	Scope-IDs gehören nicht zur Organisation, oder Schwellenwert-Modus ohne Schwellenwert.
`reportRunNotFound`	Der angeforderte Bericht-Lauf existiert für diese Organisation nicht.
`reportRunNoPdf`	Der Bericht-Lauf hat kein archiviertes PDF (Nur-E-Mail oder übersprungen).

Datenexport-Fehlercodes

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

Code	Bedeutung
`invalidExportRecipient`	(`400`) `recipientEmails` enthält eine Adresse, die kein Mitglied dieser Organisation ist. Die abgelehnten Adressen stehen in `data.unknown`.
`exportAlreadyRunning`	(`409`) Für diese Organisation läuft bereits ein Export (`queued` oder `generating`). Der laufende Export steht in `data.export`.
`exportCooldown`	(`429`) Innerhalb des Cooldown-Fensters (`data.cooldownHours`, Standard 6) wurde bereits ein Export angefordert.
`exportNotReady`	(`409`) Download angefragt, während der Export in der Warteschlange, in Arbeit oder fehlgeschlagen ist. Aktueller Stand in `data.status`.
`exportExpired`	(`410`) Das 7-Tage-Download-Fenster ist geschlossen, die Datei wurde gelöscht.
`missingExportId`	(`400`) Die Route wurde ohne Export-ID aufgerufen.

Agent-Auth-Fehlercodes

Nur lesende Agent-Zugriffstokens (wsma_, siehe Agent-Authentifizierung) sind hart auf eine GET/HEAD-Allowlist beschränkt. Jeder Schreibzugriff oder jeder Pfad außerhalb der Allowlist liefert diesen data.code:

Code	Bedeutung
`agentTokenReadOnly`	(`403`) Ein Agent-Zugriffstoken (`wsma_`) hat einen Schreibzugriff oder einen Pfad außerhalb seiner nur-lesenden Allowlist versucht. Agent-Tokens sind nur lesend.

Claim-Flow-Fehlercodes

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:

Code	Bedeutung
`service_auth_not_enabled`	(`400`) `POST /agent/identity`: der Identitätstyp `service_auth` ist auf diesem Deployment nicht aktiviert.
`invalid_claim_token`	(`400` bei `POST /agent/identity/claim` und `POST /api/agent-claim/confirm`, `404` bei `GET /api/agent-claim/context`) Der Claim-Token, Claim-Attempt-Token oder `user_code` ist unbekannt/abgelaufen/vom falschen Typ, der angemeldete Nutzer ist nicht die gebundene E-Mail, oder der Zugriff des bestätigenden Nutzers lässt sich nicht auf einen einzelnen Organisations-/Kunden-Scope auflösen.
`claimed_or_in_flight`	(`409`) `POST /agent/identity/claim`: die Registrierung ist bereits geclaimt.
`claim_expired`	(`400`) `POST /agent/identity/claim`: das äußere 24h-Claim-Fenster (ab Erstellung der Registrierung) ist verstrichen.
`authorization_pending`	(`400`) `POST /oauth2/token` mit dem Claim-Grant: der Nutzer hat noch nicht bestätigt; weiter pollen.
`slow_down`	(`400`) `POST /oauth2/token` mit dem Claim-Grant: schneller als das zurückgegebene `interval` (5s) gepollt; drossle dich.
`expired_token`	(`400`) `POST /oauth2/token` mit dem Claim-Grant: der Claim-Token/die Registrierung ist abgelaufen, wurde widerrufen oder bereits eingelöst.

Verbundene-Apps-Fehlercodes (OAuth-Verbindungen)

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:

Code	Bedeutung
`missingClientId`	(`400`) Nur `DELETE`: der Pfad-Parameter `:clientId` fehlt.
`unknownOauthConnection`	(`404`) Nur `DELETE`: der Aufrufer hat keine OAuth-Verbindung mit dieser `client_id` (bereits widerrufen, abgelaufen oder nie verbunden).

Fehlercodes für Status-Seiten-Abonnenten

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:

Code	Bedeutung
`invalidSubscriberId`	(`400`, nur Löschen) `:subscriberId` lässt sich nicht als positive Ganzzahl parsen.
`subscriberNotFound`	(`404`, nur Löschen) `:subscriberId` existiert nicht oder gehört zu einer anderen Status-Seite als `:id`.

Public IDs in DNS- und DNSBL-Monitoren

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-Fehlercodes

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:

Code	Bedeutung
`imAccessDenied`	(`403`) Der Aufrufer hat keinen Zugriff auf Incident Management: keine Session/kein Token, ein kunden-gescopter API-Token, ein Kunden-Login (`readonly`) oder `globalsupporter`-Login, oder ein Org-Login ohne IM-berechtigte Rolle (`admin`, `editor`, `responder`).
`imNotEnabled`	(`403`) Incident Management wurde für diese Organisation nicht aktiviert.
`payloadTooLarge`	(`413`, nur Events Ingest) Der Request-Body überschreitet 256 KB.
`invalidJson`	(`422`, nur Events Ingest) Der Request-Body ist kein gültiges JSON.
`payloadTooDeep`	(`422`, nur Events Ingest) Das geparste JSON-Payload ist mehr als 20 Ebenen tief verschachtelt.
`imIncidentNotFound`	(`404`) Der Incident existiert nicht oder gehört zu einer anderen Organisation.
`imIncidentInvalidStatusTransition`	(`422`, Incident bestätigen / Status ändern) Der angeforderte `status` ist für diesen Endpunkt kein gültiges Ziel (`resolved` und `merged` sind es nicht, stattdessen Incident lösen nutzen), der aktuelle Status des Incidents kann über diesen Endpunkt nicht überführt werden, oder `status` entspricht dem aktuellen Status des Incidents.
`imIncidentAlreadyClosed`	(`422`, Incident lösen) Der Incident ist bereits `resolved` oder `merged`.
`imIncidentStatusConflict`	(`409`, Status-/Resolve-Endpunkte) Der Status des Incidents hat sich zwischen Lesen und Schreiben gleichzeitig geändert. Sicher wiederholbar.
`imTeamWriteDenied`	(`403`, Incident erstellen, Schedules, Schedule-Overrides) Die Rolle des Aufrufers ist nicht `admin`, und er ist kein Team-Admin (`im_team_member.imRole = 'admin'`) des Ziel-Teams.
`imTeamNotFound`	(`404`, Schedules erstellen) `teamId` existiert nicht oder gehört zu einer anderen Organisation.
`imScheduleNotFound`	(`404`, Schedule-Overrides) `:id` existiert nicht oder gehört zu einer anderen Organisation.
`invalidTeamId`	(`422`, Incident erstellen) `teamId` gehört nicht zu deiner Organisation.
`invalidCustomerId`	(`422`, Incident erstellen) `customerId` ist angegeben, gehört aber nicht zu deiner Organisation.
`imRoutingInvalidPolicyId`	(`422`, Incident erstellen) `escalationPolicyId` ist angegeben, gehört aber nicht zu deiner Organisation.
`userNotFound`	(`404`, Schedule-Overrides hinzufügen) `userId` gehört nicht zu deiner Organisation.

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.

MFA-Fehlercodes

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:

Code	Status	Bedeutung
`mfa_enrollment_required`	`403`	Wird von jedem gegateten `/api/*`-Aufruf geliefert, wenn der Aufrufer (ein Plattform-Admin/-Supporter, sofern `MFA_ENFORCE_PLATFORM_ADMINS` aktiv ist, oder ein Mitglied einer Organisation, bei der der passende rollenbezogene Schalter `requireMfaAdmins`, `requireMfaEditors` oder `requireMfaReadonly` aktiv ist) die Zwei-Schritt-Bestätigung noch nicht eingerichtet hat. Richte die Zwei-Schritt-Bestätigung ein und wiederhole den Request.
`mfa_step_up_required`	`403`	Wird nur bei ändernden API-Token-Aufrufen geliefert (`POST`, `PATCH` und `DELETE` auf `/api/organization/tokens` sowie `POST` und `DELETE` auf `/api/customer/tokens`; kundenbezogene Tokens lassen sich nicht aktualisieren) und nur wenn der Aufrufer die Zwei-Schritt-Bestätigung aktiviert hat: Der Aufrufer hat in den letzten 5 Minuten keinen Code bestätigt. Bestätige erneut einen Code und wiederhole den Request innerhalb des 5-Minuten-Fensters. Aufrufer ohne aktivierte MFA sehen diesen Code nie, für sie funktioniert das Erstellen und Widerrufen von Tokens unverändert.
`mfa_step_up_locked`	`429`	Wird vom internen, nur session-basierten Step-up-Endpoint (`POST`, `/api/account/mfa/step-up`, nicht Teil der öffentlichen API-Oberfläche) geliefert, nachdem für dasselbe Konto 5 falsche Codes eingegeben wurden. 15 Minuten gesperrt (`data.retryAfterSeconds`); warte die Sperrzeit ab und bestätige dann erneut mit deinem Authenticator.
`nonUserSessionForbidden`	`403`	Wird von `POST /api/users/:id/mfa/reset` für jeden Aufruf mit API-Token oder Agent-Access-Token geliefert, sowie von `PATCH /api/organization`(s), wenn der Request Body `requireMfaAdmins`, `requireMfaEditors` oder `requireMfaReadonly` enthält und der Aufrufer ein API-Token oder Agent-Access-Token ist. Beide MFA-Verwaltungsaktionen erfordern eine echte, eingeloggte Benutzer-Session, ein organisations-gescoptes API-Token mit Admin-Rechten reicht nicht aus.

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

USt-IdNr.-Validierung: Fehlercodes

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:

Code	Status	Bedeutung
`vatIdMissing`	`422`	Für die Organisation ist keine `vatId` gespeichert. Setze zuerst eine mit Organisation aktualisieren.
`vatIdChangedDuringValidation`	`409`	`vatId` oder `countryCode` wurde gleichzeitig geändert, während die VIES-Abfrage lief. Das noch laufende Ergebnis wird verworfen, statt auf Daten geschrieben zu werden, die so nie geprüft wurden. Gefahrlos wiederholbar.

Update Billing Details: benötigter Body

Endpoint:

PATCH /api/organizations/:organizationPublicId/billing

Aktuell unterstützter Request-Body:

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

Der Endpoint akzeptiert derzeit nur billingEmail.

Fehlerliste und bekannte API-Fallen

Auf dieser Seite