---
title: "Fehlerliste und bekannte API-Fallen"
description: "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:

```json
{
  "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:

```json
{
  "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](/de/monitoring/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](/de/api/change-requests) 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](/docs/api/maintenance-windows/preview-occurrences)) 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](/api/organization/request-data-export)) 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](/de/api/agent-auth)) 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](/de/api/agent-auth/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](/de/api/oauth-connections)) 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](/de/api/status-pages/list-subscribers), [Löschen](/de/api/status-pages/delete-subscriber) und [Exportieren](/de/api/status-pages/export-subscribers) 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](/de/api/incident-management) (`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](/de/api/incident-management/events-ingest)) Der Request-Body überschreitet 256 KB. |
| `invalidJson` | (`422`, nur [Events Ingest](/de/api/incident-management/events-ingest)) Der Request-Body ist kein gültiges JSON. |
| `payloadTooDeep` | (`422`, nur [Events Ingest](/de/api/incident-management/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](/de/api/incident-management/acknowledge-incident)) Der angeforderte `status` ist für diesen Endpunkt kein gültiges Ziel (`resolved` und `merged` sind es nicht, stattdessen [Incident lösen](/de/api/incident-management/resolve-incident) 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](/de/api/incident-management/resolve-incident)) 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](/de/api/incident-management/create-incident), [Schedules](/de/api/incident-management/schedules), [Schedule-Overrides](/de/api/incident-management/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](/de/api/incident-management/schedules) erstellen) `teamId` existiert nicht oder gehört zu einer anderen Organisation. |
| `imScheduleNotFound` | (`404`, [Schedule-Overrides](/de/api/incident-management/schedule-overrides)) `:id` existiert nicht oder gehört zu einer anderen Organisation. |
| `invalidTeamId` | (`422`, [Incident erstellen](/de/api/incident-management/create-incident)) `teamId` gehört nicht zu deiner Organisation. |
| `invalidCustomerId` | (`422`, [Incident erstellen](/de/api/incident-management/create-incident)) `customerId` ist angegeben, gehört aber nicht zu deiner Organisation. |
| `imRoutingInvalidPolicyId` | (`422`, [Incident erstellen](/de/api/incident-management/create-incident)) `escalationPolicyId` ist angegeben, gehört aber nicht zu deiner Organisation. |
| `userNotFound` | (`404`, [Schedule-Overrides](/de/api/incident-management/schedule-overrides) hinzufügen) `userId` gehört nicht zu deiner Organisation. |

`GET /api/im/incidents`, [Incident erstellen](/de/api/incident-management/create-incident), die Status-/Resolve-Endpunkte, [Schedules](/de/api/incident-management/schedules) erstellen und [Schedule-Overrides](/de/api/incident-management/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](/de/api/organization/validate-vat-id)) 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](/de/api/organization/update-organization). |
| `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:

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

Der Endpoint akzeptiert derzeit nur `billingEmail`.