Fehlerreferenz

Diese Seite dokumentiert jeden Fehler, den die Cert-IX Scan-API zurückgeben kann, organisiert nach Kategorie.

Antwortformat

{
  "success": false,
  "error": "Lesbare Fehlerbeschreibung",
  "code": "MASCHINENLESBARER_CODE"
}

HTTP-Statuscodes

Status	Kategorie	Bedeutung
400	Client-Fehler	Ungültige Anfrage — fehlerhaftes JSON, fehlende Pflichtfelder
401	Authentifizierung	API-Schlüssel fehlt, ungültig, abgelaufen oder widerrufen
403	Autorisierung	Schlüssel gültig, aber unzureichender Bereich, IP nicht erlaubt oder Scan-Typ nicht erlaubt
404	Nicht gefunden	Ressource existiert nicht oder gehört nicht zu Ihrem Mandanten
409	Konflikt	Ressourcenstatus-Konflikt (z.B.: Abschluss eines bereits abgeschlossenen Scans abbrechen)
429	Rate-Limit	Rate-Limit oder Kontingent überschritten
500	Server-Fehler	Interner Fehler — kontaktieren Sie den Support, wenn es fortbesteht
503	Nicht verfügbar	Dienst vorübergehend nicht verfügbar — mit Backoff wiederholen

Authentifizierungsfehler (401)

Code	Nachricht	Ursache	Lösung
MISSING_API_KEY	API-Schlüssel erforderlich	Kein X-API-Key-Header angegeben	Fügen Sie den X-API-Key-Header zu Ihrer Anfrage hinzu
INVALID_API_KEY	Ungültiger API-Schlüssel	Format ist falsch oder Schlüssel existiert nicht	Stellen Sie sicher, dass der Schlüssel mit cix_sk_ beginnt
KEY_EXPIRED	API-Schlüssel ist abgelaufen	Schlüssel hat sein expiresAt-Datum überschritten	Erstellen Sie einen neuen Schlüssel oder führen Sie eine Rotation durch
KEY_REVOKED	API-Schlüssel wurde widerrufen	Schlüssel wurde explizit widerrufen	Erstellen Sie einen neuen Schlüssel
KEY_SUSPENDED	API-Schlüssel wurde gesperrt	Schlüssel wurde von einem Administrator gesperrt	Kontaktieren Sie den Administrator Ihrer Organisation

Autorisierungsfehler (403)

Code	Nachricht	Ursache	Lösung
INSUFFICIENT_SCOPE	Unzureichender Bereich: erfordert {scope}	Schlüssel hat nicht den erforderlichen Bereich	Erstellen Sie einen neuen Schlüssel mit dem benötigten Bereich
SCAN_TYPE_NOT_ALLOWED	Scan-Typ {type} nicht erlaubt	allowedScanTypes des Schlüssels enthält diese Engine nicht	Aktualisieren Sie den Schlüssel oder erstellen Sie einen, der diesen Typ erlaubt
IP_NOT_ALLOWED	Quell-IP ist nicht in der Allowlist	IP der Anfrage ist nicht in allowedIpAddresses	Fügen Sie die Quell-IP zur Allowlist hinzu oder entfernen Sie die Einschränkung
TENANT_SUSPENDED	Mandantenkonto ist gesperrt	Das Konto Ihrer Organisation wurde gesperrt	Kontaktieren Sie [email protected]

Scan-Fehler (400 / 404 / 409)

Code	HTTP	Nachricht	Lösung
SCAN_NOT_FOUND	404	Scan nicht gefunden	Überprüfen Sie die Scan-ID und den scanType-Parameter
INVALID_SCAN_TYPE	400	Ungültiger Scan-Typ: {type}	Verwenden Sie eine gültige Engine: nmap, zap, trivy, nuclei, nikto, sqlmap, wapiti, harvester, sublist3r, sentinel
INVALID_TARGET	400	Ungültiges Zielformat	Stellen Sie sicher, dass das Ziel dem erwarteten Format entspricht
INVALID_PRIORITY	400	Ungültige Priorität: {value}	Verwenden Sie: critical, high, normal oder low
SCAN_ALREADY_COMPLETED	409	Scan ist bereits abgeschlossen	Ein Scan in einem Terminalzustand kann nicht abgebrochen werden
SCAN_ALREADY_CANCELLED	409	Scan ist bereits abgebrochen	Der Scan wurde bereits abgebrochen
SCAN_ALREADY_FAILED	409	Scan ist bereits fehlgeschlagen	Ein fehlgeschlagener Scan kann nicht abgebrochen werden
RESULTS_NOT_READY	409	Ergebnisse sind noch nicht verfügbar	Warten Sie, bis der Scan den Status completed erreicht

Vorlagen-Fehler (400 / 404)

Code	HTTP	Nachricht	Lösung
TEMPLATE_NOT_FOUND	404	Scan-Vorlage nicht gefunden	Überprüfen Sie die Vorlagen-ID
TEMPLATE_NAME_REQUIRED	400	Vorlagenname ist erforderlich	Geben Sie ein name-Feld an
DUPLICATE_TEMPLATE_NAME	400	Vorlagenname existiert bereits	Verwenden Sie einen eindeutigen Namen

Webhook-Fehler (400 / 404)

Code	HTTP	Nachricht	Lösung
WEBHOOK_NOT_FOUND	404	Webhook nicht gefunden	Überprüfen Sie die Webhook-ID
INVALID_WEBHOOK_URL	400	Webhook-URL muss HTTPS verwenden	Stellen Sie sicher, dass Ihre URL mit https:// beginnt
WEBHOOK_URL_UNREACHABLE	400	Webhook-URL ist nicht erreichbar	Stellen Sie sicher, dass Ihr Endpunkt öffentlich zugänglich ist
INVALID_WEBHOOK_EVENT	400	Ungültiger Ereignistyp: {event}	Verwenden Sie gültige Ereignisse: scan.completed, scan.failed, scan.started, scan.cancelled
WEBHOOK_DISABLED	409	Webhook durch aufeinanderfolgende Fehler deaktiviert	Reaktivieren Sie mit PATCH und beheben Sie Ihren Endpunkt

Rate-Limit- und Kontingent-Fehler (429)

Code	Nachricht	Lösung
RATE_LIMIT_EXCEEDED	Rate-Limit überschritten. Versuchen Sie es in {N} Sekunden erneut.	Implementieren Sie exponentiellen Backoff; prüfen Sie den Retry-After-Header
QUOTA_EXCEEDED	Monatliches Scan-Kontingent überschritten	Upgraden Sie Ihren Plan oder warten Sie auf den nächsten Abrechnungszeitraum

Validierungsfehler (400)

Code	Nachricht	Lösung
INVALID_JSON	Anfragekörper ist kein gültiges JSON	Überprüfen Sie Ihre JSON-Syntax
MISSING_REQUIRED_FIELD	Pflichtfeld fehlt: {field}	Fügen Sie alle erforderlichen Felder hinzu
INVALID_FIELD_TYPE	Feld {field} muss vom Typ {type} sein	Korrigieren Sie den Datentyp des Feldes
INVALID_PAGE	Seite muss eine positive Ganzzahl sein	Verwenden Sie page ≥ 1
INVALID_LIMIT	Limit muss zwischen 1 und 100 liegen	Verwenden Sie limit zwischen 1 und 100

Server-Fehler (500 / 503)

Code	Nachricht	Lösung
INTERNAL_ERROR	Ein interner Serverfehler ist aufgetreten	Mit Backoff wiederholen; Support kontaktieren, wenn es fortbesteht
SERVICE_UNAVAILABLE	Dienst vorübergehend nicht verfügbar	Mit Backoff wiederholen; status.cert-ix.com prüfen
DATABASE_ERROR	Datenbankoperation fehlgeschlagen	Wiederholen; Support kontaktieren, wenn es fortbesteht
KAFKA_ERROR	Nachrichtenwarteschlange-Operation fehlgeschlagen	Wiederholen; die Warteschlange kann vorübergehend überlastet sein

Fehlerbehebungsleitfaden

« 401 — MISSING_API_KEY »

# ✅ Korrekt
curl -H "X-API-Key: cix_sk_..." https://api.cert-ix.com/scan-api/api/v1/scans

# ❌ Falsch — Schlüssel in URL-Parametern
curl "https://api.cert-ix.com/scan-api/api/v1/scans?apiKey=cix_sk_..."

« 404 — SCAN_NOT_FOUND »

Häufigste Ursachen:

1. Falscher scanType — Wenn Sie einen zap-Scan erstellt haben, müssen Sie mit ?scanType=zap abfragen
2. Falsche Scan-ID — Überprüfen Sie die UUID
3. Anderer Mandant — Schlüssel verschiedener Organisationen können die Scans der jeweils anderen nicht einsehen

« 429 — RATE_LIMIT_EXCEEDED »

Implementieren Sie exponentiellen Backoff:

import time

def anfrage_mit_backoff(func, max_versuche=5):
    for versuch in range(max_versuche):
        response = func()
        if response.status_code != 429:
            return response
        retry_after = int(response.headers.get("Retry-After", 2 ** versuch))
        time.sleep(retry_after)
    raise Exception("Maximale Anzahl an Versuchen überschritten")

---

Nächste Schritte:

• Code-Beispiele →
• Erste Schritte →
• Authentifizierung →