Technical Troubleshooting

Dieser Artikel richtet sich an Entwickler und technische Integrationspartner, die tebio über API, Webhooks oder eigene Systeme integrieren.

API-Authentifizierung

Warum erhalte ich 401 Unauthorized?

Ein 401 Unauthorized weist darauf hin, dass kein gültiger API-Schlüssel übermittelt wurde.

Prüfen Sie:

• Wird der API-Schlüssel im korrekten Header übermittelt?
• Ist der API-Schlüssel aktiv?
• Verwenden Sie den richtigen Schlüssel für Playground oder Live?
• Wurde der Schlüssel versehentlich gekürzt oder falsch kopiert?

Weitere Informationen:

• API-Schlüssel erstellen
• Fehlerbehandlung

Warum erhalte ich 403 Forbidden?

Ein 403 Forbidden bedeutet, dass der API-Schlüssel grundsätzlich gültig ist, aber nicht die erforderliche Berechtigung für die angefragte Aktion besitzt.

Prüfen Sie:

• Hat der API-Schlüssel die erforderlichen Rollen?
• Greift der Request auf den richtigen Client oder Tenant zu?
• Ist die Aktion für diese Ressource erlaubt?

Validierung und Statuskonflikte

Warum erhalte ich 422 Unprocessable Entity?

Ein 422 weist häufig auf einen fachlichen Validierungsfehler hin. Der Request ist technisch verständlich, passt aber nicht zu Geschäftsregeln oder Konfiguration.

Prüfen Sie:

• Sind alle Pflichtfelder vorhanden?
• Stimmen Produkt, Option und Tenant zusammen?
• Ist die Zahlungsmethode für das Produkt erlaubt?
• Ist der Status der Ressource für die gewünschte Aktion geeignet?

Warum erhalte ich 409 Conflict?

Ein 409 Conflict bedeutet, dass der Request nicht zum aktuellen Zustand der Ressource passt.

Beispiele:

• Subscription ist bereits gekündigt
• Bestellung wurde bereits verarbeitet
• Kampagne befindet sich nicht im passenden Status
• Änderung ist nach Start eines Prozesses nicht mehr erlaubt

Rufen Sie den aktuellen Zustand der Ressource über die API ab und passen Sie Ihren Prozess entsprechend an.

Webhooks

Warum kommt mein Webhook nicht an?

Prüfen Sie:

• Ist die Webhook-URL korrekt?
• Ist die URL öffentlich erreichbar?
• Verwendet die URL HTTPS?
• Ist das richtige Ereignis abonniert?
• Ist der Webhook für die richtige Umgebung konfiguriert?
• Antwortet Ihr System mit HTTP 2xx?

Weitere Informationen:

• Webhooks verstehen
• Webhooks einrichten

Warum wird derselbe Webhook mehrfach zugestellt?

Webhook-Ereignisse können mehrfach zugestellt werden, zum Beispiel bei Timeouts oder Retries.

Ihr System muss Webhooks idempotent verarbeiten.

Speichern Sie empfangene Event-IDs und vermeiden Sie doppelte Verarbeitung.

Asynchrone Prozesse

Warum ist der API-Aufruf erfolgreich, aber der gewünschte Folgeprozess noch nicht abgeschlossen?

Viele tebio Prozesse laufen asynchron. Ein erfolgreicher API-Status bedeutet nicht zwingend, dass Zahlung, Rechnung, Dokument oder Webhook bereits final verarbeitet wurden.

Prüfen Sie:

• Status der betroffenen Ressource
• Ereignisverlauf
• Webhook-Ereignisse
• Dokumente oder Zahlungsstatus
• spätere Fehler in Folgeprozessen

Weitere Informationen:

• Typischer API-Workflow
• Webhooks verstehen
• Events nachvollziehen

Playground und Live

Warum funktioniert ein Request im Playground, aber nicht in Live?

Playground und Live sind getrennte Umgebungen.

Prüfen Sie:

• Verwenden Sie den richtigen API-Schlüssel?
• Existieren Produkt, Option, Tenant und Konfiguration auch in Live?
• Sind Zahlungsmethoden in Live korrekt aktiviert?
• Sind Webhooks in Live separat eingerichtet?
• Sind Steuern, Fakturierung und Rechnungseinstellungen produktiv konfiguriert?

Support kontaktieren

Wenn Sie den 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
• gekürzter Request Body ohne Secrets
• gekürzter Response Body
• betroffene Kunden-, Bestell-, Subscription- oder Rechnungs-ID
• externe Referenz
• Webhook-Event-ID, falls relevant