Häufige API-Fehler

Bei der Integration der tebio API können Fehler auf unterschiedlichen Ebenen auftreten. Dazu gehören fehlerhafte Request-Daten, fehlende Berechtigungen, ungültige Statusübergänge, Rate Limits, Netzwerkprobleme oder asynchrone Folgefehler.

Dieser Artikel erklärt häufige API-Fehler und zeigt, wie Sie diese systematisch prüfen und beheben können.

Für grundlegende Konzepte zur Fehlerbehandlung lesen Sie zusätzlich den Artikel Fehlerbehandlung.

Fehlerarten im Überblick

API-Fehler lassen sich grob in folgende Kategorien einteilen:

Fehlerart	Typische Ursache	Typische Statuscodes
Authentifizierung	API-Schlüssel fehlt, ist ungültig oder gehört zur falschen Umgebung	`401`
Berechtigung	API-Schlüssel hat nicht die erforderlichen Rollen oder Tenant-Rechte	`403`
Validierung	Pflichtfelder fehlen oder Werte sind fachlich ungültig	`400`, `422`
Statuskonflikt	Aktion passt nicht zum aktuellen Zustand der Ressource	`409`
Nicht gefunden	Ressource oder ID existiert nicht oder ist nicht zugänglich	`404`
Rate Limit	zu viele Requests in kurzer Zeit	`429`
Temporärer Fehler	Timeout, Wartung oder technischer Fehler	`5xx`

Fehlerantwort der API

Wenn ein API-Request fehlschlägt, kann die API eine strukturierte Fehlerantwort zurückgeben.

Eine typische Fehlerantwort kann zum Beispiel so aussehen:

{
  "errorCode": 9998,
  "errorText": "Validation Error",
  "errorDomain": "SUBSCRIPTION_MANAGEMENT",
  "errorSeverity": "ERROR",
  "errorCause": "The provided UUID is malformed.",
  "contextEntries": [
    {
      "contextLabel": "reason",
      "contextValue": "customer_id must be a valid UUID"
    }
  ]
}

Typische Bestandteile:

Feld	Bedeutung
`errorCode`	numerischer oder technischer Fehlercode
`errorText`	kurze Beschreibung des Fehlers
`errorDomain`	betroffener Fach- oder Servicebereich
`errorSeverity`	Schweregrad des Fehlers
`errorCause`	genauere technische oder fachliche Ursache, sofern verfügbar
`contextEntries`	zusätzliche Kontextinformationen, zum Beispiel betroffene Felder oder Validierungsgründe

Die genaue Struktur und die verfügbaren Felder können je nach Endpunkt und Fehlerart variieren. Maßgeblich ist die technische API-Referenz.

Häufige HTTP-Statuscodes

`400 Bad Request`

Der Request konnte nicht korrekt verarbeitet werden, weil er syntaktisch fehlerhaft oder unvollständig ist.

Typische Ursachen:

ungültiges JSON
falscher Datentyp
fehlendes Pflichtfeld
ungültiges Datumsformat
ungültiger ENUM-Wert
unvollständiger Request Body

Prüfen Sie:

Ist der Request Body gültiges JSON?
Entsprechen alle Felder dem Schema in der API-Referenz?
Sind alle Pflichtfelder vorhanden?
Werden Datums- und Zeitwerte im erwarteten Format übergeben?
Werden ENUM-Werte exakt wie dokumentiert geschrieben?

Empfohlene Reaktion:

Request korrigieren
nicht unverändert wiederholen
Fehlerdetails aus der Response auswerten

`401 Unauthorized`

Die Authentifizierung ist fehlgeschlagen.

Typische Ursachen:

API-Schlüssel fehlt
API-Schlüssel ist ungültig
API-Schlüssel wurde falsch kopiert
falscher Authorization-Header
API-Schlüssel gehört zur falschen Umgebung
API-Schlüssel wurde deaktiviert

Prüfen Sie:

Wird der API-Schlüssel im richtigen Header übermittelt?
Ist der API-Schlüssel vollständig und unverändert?
Verwenden Sie den richtigen Schlüssel für Playground oder Live?
Ist der API-Schlüssel im Business-Portal noch aktiv?
Wird der Schlüssel versehentlich mit Leerzeichen oder Zeilenumbrüchen übermittelt?

Empfohlene Reaktion:

API-Schlüssel prüfen
Umgebung prüfen
Schlüssel bei Bedarf neu erstellen
keine automatische Wiederholung ohne Konfigurationsänderung

Weitere Informationen:

`403 Forbidden`

Die Authentifizierung war erfolgreich, aber die Berechtigung für die angefragte Aktion fehlt.

Typische Ursachen:

API-Schlüssel hat nur Lesezugriff
erforderliche Rolle fehlt
Zugriff auf falschen Client oder Tenant
Aktion ist für diese Ressource nicht erlaubt
API-Schlüssel ist nicht für den gewünschten Bereich freigegeben

Prüfen Sie:

Hat der API-Schlüssel die erforderlichen Rollen?
Greift der Request auf den richtigen Client oder Tenant zu?
Ist die angefragte Aktion für den API-Schlüssel erlaubt?
Wird ein Endpoint verwendet, der zusätzliche Berechtigungen benötigt?

Empfohlene Reaktion:

Rollen und Berechtigungen im Business-Portal prüfen
API-Schlüssel mit minimal erforderlichen Rechten anpassen
Request nicht unverändert wiederholen

`404 Not Found`

Die angefragte Ressource wurde nicht gefunden oder ist für den API-Schlüssel nicht zugänglich.

Typische Ursachen:

UUID ist falsch
Ressource existiert nicht
Ressource gehört zu einem anderen Tenant
Ressource wurde deaktiviert oder gelöscht
falsche Umgebung: ID aus Playground wird in Live verwendet oder umgekehrt
falscher Endpoint

Prüfen Sie:

Ist die ID korrekt?
Existiert die Ressource in derselben Umgebung?
Gehört die Ressource zum richtigen Tenant?
Wird der richtige Endpoint verwendet?
Wurde die Ressource möglicherweise deaktiviert?

Empfohlene Reaktion:

ID und Umgebung prüfen
Ressource über Search-Endpunkt suchen
externe Referenzen und gespeicherte IDs prüfen

`409 Conflict`

Der Request steht im Konflikt mit dem aktuellen Zustand der Ressource.

Typische Ursachen:

Subscription ist bereits gekündigt
Bestellung wurde bereits verarbeitet
Rechnung ist bereits finalisiert oder storniert
Zahlung wurde bereits verarbeitet
Kampagne ist nicht im passenden Status
eine Aktion wurde bereits ausgelöst
ein Statusübergang ist fachlich nicht erlaubt

Prüfen Sie:

Welchen aktuellen Status hat die Ressource?
Wurde die Aktion bereits ausgeführt?
Gibt es einen asynchronen Folgeprozess, der noch läuft?
Ist der gewünschte Statusübergang fachlich erlaubt?
Gibt es im Ereignisverlauf Hinweise auf vorherige Aktionen?

Empfohlene Reaktion:

aktuellen Zustand per API abrufen
eigenen Prozess an den Status anpassen
Request nicht blind wiederholen
bei Bedarf fachliche Folgeaktion verwenden, zum Beispiel Storno, Korrektur oder neue Bestellung

Weitere Informationen:

`422 Unprocessable Entity`

Der Request ist syntaktisch verständlich, aber fachlich ungültig.

Typische Ursachen:

Pflichtfeld fehlt
Wert ist fachlich nicht erlaubt
Produkt passt nicht zum Tenant
Option gehört nicht zum Produkt
Zahlungsmethode ist für das Produkt nicht erlaubt
Steuer- oder Rechnungskonfiguration passt nicht
Statuswert ist nicht zulässig
Konfiguration ist unvollständig

Häufige tebio Error Codes in diesem Zusammenhang:

9998 Validierungsfehler
9006 ungültige Verknüpfung oder Zuordnung
weitere endpoint-spezifische Fehlercodes laut API-Referenz

Prüfen Sie:

Welche Felder werden in contextEntries genannt?
Passt das Produkt zur Tenant- und Produktkonfiguration?
Gehört die Option zum ausgewählten Produkt?
Ist die Zahlungsmethode erlaubt?
Ist die Ressource im richtigen Status?
Sind alle abhängigen Einstellungen im Business-Portal konfiguriert?

Empfohlene Reaktion:

Fehlerdetails auswerten
Payload korrigieren
fachliche Konfiguration prüfen
Request nicht unverändert wiederholen

`429 Too Many Requests`

Das Rate Limit wurde überschritten.

Typische Ursachen:

zu viele Requests in kurzer Zeit
zu viele parallele Synchronisationsläufe
zu kleine Batchgrößen mit hoher Frequenz
Polling statt Webhooks
fehlende Drosselung im API-Client

Prüfen Sie:

Werden Requests unnötig häufig gesendet?
Gibt es parallele Jobs mit denselben Daten?
Wird ein Search-Endpunkt ohne ausreichende Filterung regelmäßig abgefragt?
Wird ein Retry-After Header zurückgegeben?
Können Webhooks statt Polling verwendet werden?

Empfohlene Reaktion:

Verarbeitung pausieren
Retry-After berücksichtigen, sofern vorhanden
Exponential Backoff verwenden
Batch- und Synchronisationslogik optimieren
Webhooks einsetzen, wenn externe Systeme auf Änderungen reagieren sollen

Weitere Informationen:

`500 Internal Server Error`

Ein unerwarteter serverseitiger Fehler ist aufgetreten.

Typische Ursachen:

temporärer technischer Fehler
unerwarteter Backend-Fehler
nachgelagerter Dienst nicht verfügbar
technische Ausnahme während der Verarbeitung

Prüfen Sie:

Tritt der Fehler reproduzierbar auf?
Ist nur ein einzelner Request betroffen?
Enthält die Response eine Fehler-ID oder Referenz?
Gibt es zeitgleich bekannte Wartungsarbeiten oder Störungen?
Ist der Request fachlich plausibel und entspricht der API-Referenz?

Empfohlene Reaktion:

Request mit begrenzter Retry-Strategie wiederholen, sofern idempotent
Exponential Backoff verwenden
Fehler protokollieren
bei dauerhaftem Fehler Support kontaktieren

`503 Service Unavailable`

Der angefragte Service ist temporär nicht verfügbar.

Typische Ursachen:

Wartungsarbeiten
temporäre Überlast
nachgelagerter Dienst nicht erreichbar
Infrastrukturproblem

Prüfen Sie:

Ist der Fehler temporär?
Betrifft er mehrere Endpunkte?
Gibt es ein Wartungsfenster?
Tritt der Fehler auch nach kurzer Wartezeit erneut auf?

Empfohlene Reaktion:

später erneut versuchen
Retry mit Backoff verwenden
keine sofortigen Endlosschleifen implementieren
Fehler im Monitoring sichtbar machen

Typische tebio Error Codes

Neben HTTP-Statuscodes können tebio Error Codes zusätzliche Hinweise auf die Fehlerursache geben.

`9998`: Validation Error

Der Request enthält ungültige oder unvollständige Daten.

Typische Ursachen:

Pflichtfeld fehlt
Wert hat falsches Format
ungültige UUID
ungültiger ENUM-Wert
fachliche Validierung schlägt fehl

Prüfen Sie:

contextEntries
errorCause
betroffene Felder
Request Body gegen API-Referenz
fachliche Konfiguration im Business-Portal

Empfohlene Reaktion:

Payload korrigieren
Validierung im eigenen System ergänzen
Fehler für Benutzer verständlich anzeigen

`1305`: Duplicate Name

Ein Name ist bereits vergeben.

Typische Ursachen:

Kategorie, Tag, Vorlage oder Eigenschaft existiert bereits
Name muss innerhalb des Tenants eindeutig sein
Objekt existiert, wird aber durch Filter nicht angezeigt
ein inaktives Objekt verwendet den Namen bereits

Prüfen Sie:

existiert das Objekt bereits?
sind Filter aktiv?
gibt es inaktive oder ausgeblendete Objekte?
muss statt Create ein Update verwendet werden?

Empfohlene Reaktion:

eindeutigen Namen verwenden
vorhandenes Objekt wiederverwenden oder aktualisieren
Duplikatprüfung im externen System ergänzen

`9006`: Invalid Association

Eine Verknüpfung oder Zuordnung ist ungültig.

Typische Ursachen:

Option gehört nicht zum Produkt
Tag ist für diesen Kontext nicht erlaubt
Eigenschaft passt nicht zur Entität
Produkt- oder Optionskonfiguration passt nicht zum Tenant
Verknüpfung ist fachlich nicht zulässig

Prüfen Sie:

Produkt- und Optionsbezug
Tenant-Zuordnung
erlaubte Eigenschaften oder Tags
Konfiguration im Produktkatalog
API-Referenz für erlaubte Relationen

Empfohlene Reaktion:

Verknüpfung korrigieren
gültige Produkt- oder Optionsdaten verwenden
Produktdaten regelmäßig synchronisieren

`9219`: Payment Transaction Error

Eine Zahlung oder Zahlungstransaktion konnte nicht erfolgreich verarbeitet werden.

Typische Ursachen:

Zahlungsanbieter lehnt Transaktion ab
Kreditkarte ist abgelaufen
SEPA-Lastschrift wurde abgewiesen
Konto ist nicht gedeckt
Mandat oder Zahlungsdaten sind ungültig
Erstattung konnte nicht verarbeitet werden
externe Zahlungsplattform meldet einen Fehler

Prüfen Sie:

Zahlungsstatus
Transaktionsdetails
Rückmeldung des Zahlungsanbieters
Zahlungsmethode des Kunden
Mandat oder Zahlungsdaten
Ereignisverlauf

Empfohlene Reaktion:

Zahlungsdaten aktualisieren
Zahlung erneut auslösen, sofern fachlich erlaubt
Kunde oder Finance-Team informieren
Fehlerdetails im Supportfall bereitstellen

Weitere Informationen:

Fehler bei asynchronen Folgeprozessen

Nicht jeder Fehler wird direkt im API-Response sichtbar.

Ein Request kann erfolgreich angenommen werden, während ein späterer Folgeprozess fehlschlägt.

Beispiele:

Bestellung wurde angenommen, aber Zahlung schlägt später fehl
Subscription wurde erstellt, aber Dokumenterzeugung schlägt fehl
Rechnung wurde erstellt, aber Webhook-Zustellung schlägt fehl
Kampagnenausführung wurde gestartet, aber einzelne Empfängerprozesse schlagen fehl
Nachricht konnte nicht versendet werden

Prüfen Sie in solchen Fällen:

Status der betroffenen Ressource
Ereignisverlauf
Webhook-Ereignisse
Zahlungsstatus
Dokumentstatus
Portalansicht der betroffenen Ressource

Weitere Informationen:

Debugging-Checkliste

Wenn ein API-Fehler auftritt, prüfen Sie schrittweise:

Verwenden Sie die richtige Umgebung: Playground oder Live?
Ist der API-Schlüssel gültig und aktiv?
Hat der API-Schlüssel die erforderlichen Berechtigungen?
Ist der Endpoint korrekt?
Ist die HTTP-Methode korrekt?
Ist der Request Body gültiges JSON?
Sind alle Pflichtfelder vorhanden?
Stimmen Datentypen, ENUM-Werte und Datumsformate?
Gehören Produkt, Option, Tenant und Zahlungsmethode zusammen?
Ist die Ressource im passenden Status?
Wurde die Aktion bereits ausgeführt?
Enthält die Fehlerantwort contextEntries oder errorCause?
Gibt es relevante Ereignisse im Portal?
Ist ein asynchroner Folgeprozess betroffen?
Sind Webhooks korrekt verarbeitet worden?

Was Sie dem Support senden sollten

Wenn Sie einen API-Fehler nicht selbst lösen können, senden Sie dem tebio Support möglichst folgende Informationen:

Umgebung: Playground oder Live
Zeitpunkt des Fehlers
Endpoint und HTTP-Methode
HTTP-Statuscode
vollständiger errorCode
errorText
errorDomain
errorCause, sofern vorhanden
contextEntries, sofern vorhanden
gekürzter Request Body ohne Secrets
gekürzter Response Body
betroffene tebio ID, zum Beispiel Customer, Order, Subscription, Invoice oder Payment
externe Referenz aus Ihrem System
Webhook-Event-ID, falls relevant
kurze Beschreibung, was Ihr System erreichen wollte

Wichtig: Senden Sie keine API-Schlüssel, Passwörter, vollständigen Zahlungsdaten oder andere Secrets.

Typische Fehler vermeiden

Nur den HTTP-Statuscode loggen

Der HTTP-Statuscode allein reicht oft nicht aus. Loggen Sie zusätzlich den strukturierten Fehlerkörper.

`4xx`-Fehler automatisch wiederholen

Ein unveränderter Retry löst Validierungs-, Berechtigungs- oder Statusfehler in der Regel nicht.

Keine Idempotenz für kritische Requests einplanen

Retries können bei Create- oder Action-Requests zu doppelten Prozessen führen, wenn keine Idempotenz vorgesehen ist.

Playground-IDs in Live verwenden

IDs aus Playground und Live sind nicht austauschbar.

Produktdaten nicht synchronisieren

Veraltete Produkt-, Options- oder Preis-IDs führen häufig zu Validierungs- oder Zuordnungsfehlern.

Webhooks ignorieren

Viele Folgefehler werden nicht im ursprünglichen API-Response sichtbar, sondern später über Status, Ereignisverlauf oder Webhooks.

Häufige API-Fehler

Fehlerarten im Überblick

Fehlerantwort der API

Häufige HTTP-Statuscodes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

503 Service Unavailable

Typische tebio Error Codes

9998: Validation Error

1305: Duplicate Name

9006: Invalid Association

9219: Payment Transaction Error

Fehler bei asynchronen Folgeprozessen

Debugging-Checkliste

Was Sie dem Support senden sollten

Typische Fehler vermeiden

Nur den HTTP-Statuscode loggen

4xx-Fehler automatisch wiederholen

Keine Idempotenz für kritische Requests einplanen

Playground-IDs in Live verwenden

Produktdaten nicht synchronisieren

Webhooks ignorieren

Verwandte Themen

`400 Bad Request`

`401 Unauthorized`

`403 Forbidden`

`404 Not Found`

`409 Conflict`

`422 Unprocessable Entity`

`429 Too Many Requests`

`500 Internal Server Error`

`503 Service Unavailable`

`9998`: Validation Error

`1305`: Duplicate Name

`9006`: Invalid Association

`9219`: Payment Transaction Error

`4xx`-Fehler automatisch wiederholen