Zum Hauptinhalt springen

Einheit 15 — Debugging-Strategie

Was du nach dieser Einheit weißt: Du hast einen systematischen Diagnoseweg wenn eine API-Integration nicht funktioniert — von der Netzwerkebene bis zum Post-Agent-Output.

Das Prinzip: von außen nach innen​

Fehler bei API-Integrationen haben immer eine Ebene. Man findet sie am schnellsten wenn man systematisch von außen nach innen vorgeht — statt sofort in der Agent-Konfiguration zu suchen.

Ebene 1: Netzwerk (kommt die Verbindung überhaupt durch?)
Ebene 2: Authentifizierung (wird das Token akzeptiert?)
Ebene 3: Request-Struktur (ist der Body korrekt?)
Ebene 4: Geschäftslogik (sind die Werte valide?)
Ebene 5: 42°OS-Konfiguration (ist der Agent richtig konfiguriert?)

Stufe 1: Netzwerk​

Tool: CURL auf dem 42°OS-Server

# Auf dem 42°OS-Server per SSH:
curl -v https://api.example.com/

Erwartetes Ergebnis:

* Trying 185.42.11.93:443...
* Connected
* SSL handshake complete
< HTTP/1.1 200 OK

Fehlerbilder:

curl: (6) Could not resolve host: api.example.com
→ DNS-Problem: Hostname nicht auflösbar vom Server
→ Prüfen: Interner DNS-Server konfiguriert? Hostname nur intern gültig?

curl: (7) Failed to connect to api.example.com port 443
→ TCP-Verbindung gescheitert: Firewall blockiert
→ Prüfen: Firewall-Freigabe für Server-IP vorhanden?

curl: (60) SSL certificate problem: self signed certificate
→ SSL-Zertifikat nicht vertrauenswürdig
→ Kurzfristig: --insecure hinzufügen
→ Langfristig: CA-Zertifikat importieren

Stufe 2: Authentifizierung​

curl -v https://api.example.com/v1/customers \
  -H "Authorization: Bearer dein_token"

401 → Token-Problem:

  • Token falsch kopiert (Leerzeichen, Zeilenumbruch)
  • Token abgelaufen
  • Falsches Format (Bearer fehlt oder ist groß/klein)
  • Falscher Endpunkt für Token-Generierung

403 → Berechtigungs-Problem:

  • Token gültig, aber Konto hat keine Rechte auf diesen Endpunkt
  • API-Konto braucht spezifische Rolle/Berechtigung
  • Falscher Scope bei OAuth

Stufe 3: Request-Struktur​

curl -X POST https://api.example.com/v1/orders \
  -H "Authorization: Bearer dein_token" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": 42, "quantity": 3}' \
  -v

400 Bad Request → Body-Problem:

  • JSON-Syntaxfehler (Komma vergessen, falsche Anführungszeichen)
  • Pflichtfeld fehlt
  • Falscher Datentyp (String statt Integer)

Tipp: Den Response Body lesen — er enthält fast immer Details:

{"error": "customer_id must be an integer, got string '42'"}

404 → URL-Problem:

  • Endpunkt existiert nicht in dieser API-Version
  • Pfad-Parameter falsch (ID existiert nicht)
  • Tippfehler in der URL

Stufe 4: In Postman verifizieren​

Wenn CURL klappt, der Post Agent aber nicht — Problem liegt in der Übersetzung.

Postman-Import: CURL-Befehl importieren → läuft es in Postman?

Dann Schritt für Schritt den Post Agent nachbauen:

  1. Nur URL → testen
  2. URL + Authorization → testen
  3. URL + Authorization + Body → testen
  4. URL + Authorization + Body + dynamische Werte → testen

Stufe 5: Post Agent in 42°OS​

Wenn alles vorher klappt, der Post Agent aber nicht:

Logs lesen: Agent-Logs zeigen den exakten Request der abgeschickt wurde und die Response.

Häufige Fehler:

  • Liquid-Template wird nicht aufgelöst → Variable fehlt in der eingehenden Nachricht
  • body wird nicht geparst → JSON Parse Agent fehlt
  • Credentials-Name falsch → {% credential name %} findet keinen Eintrag
  • SSL-Verifikation schlägt fehl → in Agent-Konfiguration deaktivieren

Testlauf mit manueller Nachricht:

{
  "customer_id": 42,
  "product_id": 789,
  "quantity": 3
}

Manual Message Agent vor Post Agent → testen ob der Agent mit festen Werten funktioniert, bevor dynamische Werte aus echten Quellen getestet werden.

Das vollständige Diagnose-Schema​

Problem: API-Aufruf aus 42°OS funktioniert nicht
│
├─ Schritt 1: CURL auf 42°OS-Server
│   ├─ DNS-Fehler → IT: DNS konfigurieren
│   ├─ Timeout → IT: Firewall-Freigabe
│   ├─ SSL-Fehler → --insecure testen / Zertifikat importieren
│   └─ HTTP-Antwort → weiter zu Schritt 2
│
├─ Schritt 2: Mit Authentifizierung
│   ├─ 401 → Credentials prüfen, Token erneuern
│   ├─ 403 → Berechtigungen prüfen
│   └─ 200/4xx → weiter zu Schritt 3
│
├─ Schritt 3: Mit vollständigem Request
│   ├─ 400 → Response Body lesen, Felder prüfen
│   ├─ 404 → URL prüfen
│   └─ 201/200 → API funktioniert, weiter zu Schritt 4
│
├─ Schritt 4: In Postman
│   ├─ Klappt nicht → CURL und Postman vergleichen
│   └─ Klappt → weiter zu Schritt 5
│
└─ Schritt 5: Post Agent in 42°OS
    ├─ Logs lesen
    ├─ Liquid-Templates prüfen
    ├─ Mit Manual Message Agent testen
    └─ Credentials-Store prüfen

Damit ist Kurs 3 abgeschlossen.

Du hast jetzt das vollständige Werkzeugset: Konzepte (Einheiten 1–6), Infrastruktur (Einheiten 7–10), Praxis-Tools und Debugging (Einheiten 11–15). APIs, die vorher wie eine Blackbox wirkten, sind jetzt transparent und systematisch lösbar.