Fehlerbehandlung

Diese Seite beschreibt die HTTP-Statuscodes, Fehler-Responses und Lösungsansätze für häufige Probleme – sowohl für die REST API als auch für Hardware-Integrationen.

HTTP-Statuscodes

⚠️ Wichtig: Bei Status 200 kann das Ticket trotzdem ungültig sein! Prüfen Sie immer das valid-Feld in der Response (REST API) bzw. AcsRes (Hardware).

REST API – Fehler-Responses

Response-Format

Bei HTTP-Fehlern (4xx, 5xx) erhalten Sie eine JSON-Response:

{
  "valid": false,
  "status": "rejected",
  "reason": "error_code",
  "message": "Lesbare Fehlerbeschreibung"
}

400 – Bad Request

Ursache: Der Request-Body ist ungültig oder das Feld ticketCode fehlt.

{
  "valid": false,
  "status": "rejected",
  "reason": "missing_ticket_code",
  "message": "ticketCode ist erforderlich"
}

Lösung:

• Prüfen Sie, ob Content-Type: application/json gesetzt ist
• Stellen Sie sicher, dass der Body gültiges JSON enthält
• Das Feld ticketCode muss vorhanden und nicht leer sein

# ❌ Falsch
curl -X POST https://scan.tikflow.de/scan/validate \
  -H "x-api-key: YOUR_KEY"
 
# ✅ Richtig
curl -X POST https://scan.tikflow.de/scan/validate \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticketCode": "TK1.tkt_xxx.xxx"}'

401 – Unauthorized

Ursache: Der API-Key fehlt oder ist ungültig.

{
  "message": "Forbidden"
}

Lösung:

• Prüfen Sie, ob der Header x-api-key gesetzt ist
• Stellen Sie sicher, dass der Key korrekt kopiert wurde (keine Leerzeichen)
• Prüfen Sie im Dashboard, ob der Key noch aktiv ist

# ❌ Falsch (Header fehlt)
curl -X POST https://scan.tikflow.de/scan/validate
 
# ❌ Falsch (falscher Header-Name)
curl -X POST https://scan.tikflow.de/scan/validate \
  -H "Authorization: Bearer YOUR_KEY"
 
# ✅ Richtig
curl -X POST https://scan.tikflow.de/scan/validate \
  -H "x-api-key: YOUR_KEY"

403 – Forbidden

Ursache: Der API-Key hat keinen Zugriff auf das Event dieses Tickets.

{
  "valid": false,
  "status": "rejected",
  "reason": "event_not_allowed",
  "message": "API-Key hat keinen Zugriff auf dieses Event"
}

Lösung:

• Prüfen Sie den Event-Scope des API-Keys im Dashboard
• Fügen Sie das Event zum Key hinzu oder setzen Sie den Scope auf „Alle Events"
• Erstellen Sie bei Bedarf einen separaten Key für dieses Event

404 – Not Found

Ursache: Das Ticket mit diesem Code existiert nicht.

{
  "valid": false,
  "status": "not_found",
  "message": "Ticket nicht gefunden"
}

Lösung:

• Prüfen Sie, ob der Ticket-Code vollständig ist
• Stellen Sie sicher, dass das richtige Format verwendet wird (z.B. TK1.tkt_xxx.xxx)
• Das Ticket wurde möglicherweise gelöscht oder existierte nie

429 – Too Many Requests

Ursache: Das Rate Limit wurde überschritten.

{
  "message": "Too Many Requests"
}

Lösung:

• Warten Sie kurz und versuchen Sie es erneut
• Implementieren Sie exponentielles Backoff in Ihrer Anwendung
• Prüfen Sie, ob Ihre Anwendung unnötig viele Requests sendet

Rate Limits:

500 – Internal Server Error

Ursache: Ein unerwarteter Fehler auf dem Server.

Lösung:

• Warten Sie kurz und versuchen Sie es erneut
• Falls der Fehler wiederholt auftritt, kontaktieren Sie den TikFlow Support

Hardware – Fehler-Responses

Bei Hardware-Integrationen gibt TikFlow die Fehlermeldung im Geräte-eigenen Format zurück. Das Gerät zeigt die Meldung typischerweise auf dem integrierten Display an.

Cloud B4 – Fehlerformat

💡 Bei AcsRes: "0" bleibt das Drehkreuz / die Tür gesperrt. Der Besucher sieht die Meldung im Note-Feld auf dem Gerätedisplay.

Timeout / keine Verbindung

Wenn der TikFlow-Server nicht rechtzeitig antwortet, verhält sich der B4 Controller je nach Konfiguration:

ℹ️ Ausführliche Hardware-Fehlerbehebung unter Hardware-Integration → Fehlerbehebung

Ticket-Status vs. HTTP-Status

Es ist wichtig, den Unterschied zu verstehen:

Beispiel: HTTP 200, aber Ticket ungültig

REST API:

{
  "valid": false,
  "status": "exhausted",
  "message": "Ticket hat keine verbleibenden Nutzungen",
  "ticketId": "tkt_abc123",
  "usesAllowed": 10,
  "usesConsumed": 10,
  "usesRemaining": 0
}

Hardware (Cloud B4):

{
  "ActIndex": "0",
  "AcsRes": "0",
  "Time": "0",
  "Note": "Ticket erschöpft"
}

💡 Best Practice: Prüfen Sie bei Status 200 immer das Feld valid (REST API) bzw. AcsRes (Hardware), bevor Sie den Einlass gewähren.

Troubleshooting-Checkliste

REST API

TikFlow Hardware

Error Handling Best Practices

REST API (JavaScript)

async function scanTicket(ticketCode) {
  try {
    const response = await fetch('https://scan.tikflow.de/scan/consume', {
      method: 'POST',
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ ticketCode })
    });
 
    const data = await response.json();
 
    // HTTP-Fehler behandeln
    if (!response.ok) {
      if (response.status === 429) {
        // Rate Limit: Warten und erneut versuchen
        await sleep(1000);
        return scanTicket(ticketCode);
      }
      throw new Error(data.message || 'API-Fehler');
    }
 
    // Ticket-Status prüfen (auch bei HTTP 200!)
    if (data.valid) {
      // ✅ Einlass gewähren
      openGate();
    } else {
      // ❌ Einlass verweigern
      showError(data.message);
    }
 
  } catch (error) {
    // Netzwerk- oder andere Fehler
    showError('Verbindungsfehler – bitte erneut versuchen');
  }
}

ℹ️ Für Hardware-Integrationen ist kein eigener Error-Handling-Code nötig – TikFlow und das Gerät kommunizieren direkt miteinander.