Einstieg / Konventionen

Konventionen

Diese Regeln gelten für jeden Aufruf der REST-API, auch wenn die Seite eines Endpunkts sie nicht eigens nennt.

Fehler

Jede Fehlerantwort hat denselben Körper:

HTTP/1.1 404 Not Found
x-request-id: req_9b1e44af0c37d2e5

{
"code": "not_found",
"message": "Domain nicht gefunden.",
"request_id": "req_9b1e44af0c37d2e5"
}

Werten Sie code aus. message ist deutscher Text für Menschen und kann sich ändern. details ist optional und je Code verschieden aufgebaut.

Jede Antwort trägt den Kopf x-request-id, auch eine erfolgreiche. Bei Fehlern steht derselbe Wert als request_id im Körper. Nennen Sie ihn, wenn Sie sich an den Support wenden. Schicken Sie selbst einen Kopf x-request-id mit, übernimmt die API ihn, solange er höchstens 64 Zeichen aus A-Z, a-z, 0-9, _ und - hat.

Fehlercodes

Welche Codes ein einzelner Aufruf liefern kann, steht auf seiner Seite unter den Antwortcodes.

Paginierung

Listen mit vielen Einträgen werden seitenweise ausgeliefert, mit einem Cursor. Das gilt für GET /v1/domains, GET /v1/scans, GET /v1/clients, GET /v1/reports und GET /v1/billing/usage/scans/entries.

Die Antwort hat die Form { "items": [...], "next_cursor": "..." }. Steht next_cursor auf null, ist das die letzte Seite. Behandeln Sie den Cursor als undurchsichtige Zeichenkette. Einen Cursor, den die API nicht lesen kann, beantwortet sie mit 400 validation_failed.

Kürzere Listen kommen ohne Seiten als ganzes Array, etwa die Zeitpläne und die Quittierungen einer Domain. Ein Beispiel für das Blättern steht unter Scans auflisten.

Rate-Limits

Anfragen mit API-Schlüssel werden je Kalenderminute gezählt, REST und MCP zusammen:

Wer darüber liegt, bekommt 429 mit dem Code rate_limited. Der Kopf Retry-After nennt die Sekunden bis zum Beginn der nächsten Minute. details sagt, welche Grenze gegriffen hat:

HTTP/1.1 429 Too Many Requests
Retry-After: 17

{
"code": "rate_limited",
"message": "Zu viele Anfragen mit diesem API-Schlüssel: höchstens 30 je Minute. Bitte 17 Sekunden warten.",
"details": { "scope": "api_key", "limit": 30, "retry_after": 17 },
"request_id": "req_9b1e44af0c37d2e5"
}

details.scope ist api_key oder organization. Warten Sie die genannte Zeit ab, bevor Sie es erneut versuchen. Auch eine abgewiesene Anfrage zählt mit.

Domain-Einschränkung

Ein Schlüssel kann auf einzelne Domains der Organisation beschränkt sein. Für ihn existieren die übrigen Domains nicht: Listen lassen sie aus, und ein Aufruf auf eine solche Domain, ihre Läufe oder ihre Zeitpläne endet mit 404 not_found. Ein 403 würde verraten, dass es die Domain gibt.

Die Nutzung gilt für die ganze Organisation. Ein Schlüssel mit Domain-Einschränkung liest sie deshalb nicht und bekommt dort 403 api_key_scope_insufficient, auch mit dem Recht full oder read_only.

Keine Webhooks

Redcheck ruft keine Adresse bei Ihnen auf, wenn ein Lauf fertig ist. Für Automatik gibt es zwei Wege:

• Abfragen von GET /v1/scans/{id}, bis status einen Endzustand erreicht. Fragen Sie dabei höchstens alle fünf Sekunden.
• Der Ereignisstrom GET /v1/scans/{id}/stream als Server-Sent Events, der mit dem Ereignis done endet.

POST /v1/billing/webhook steht zwar im Vertrag, nimmt aber nur Meldungen des Zahlungsdienstleisters an.

Zugang nach Plan

Die API prüft den Plan bei jedem Aufruf. Fällt eine Organisation auf Free zurück, ruhen ihre Schlüssel: jeder Aufruf endet mit 402 plan_upgrade_required. Widerrufen wird dabei nichts. Mit der Rückkehr zu Pro oder Agentur gelten dieselben Schlüssel wieder. Ein Schlüssel einer Pro-Organisation bekommt am MCP-Server ebenfalls plan_upgrade_required.