MostlyQR

Fehler

Die REST API verwendet Standard-HTTP-Statuscodes und gibt einen JSON-Error-Body zurück:

json
{ "error": "unauthorized", "message": "Missing or invalid API key" }

# Statuscodes

Status error Wann
400 invalid-argument Malformed body oder ein fehlendes erforderliches Feld.
401 unauthorized Fehlender, ungültiger oder widerrufener API-Schlüssel.
403 permission-denied Über die Berechtigung deines Plans hinaus (ein Feature, das dein Plan nicht umfasst).
404 not-found Kein Link/Kampagne/Job mit dieser ID, oder nicht im Besitz deines Kontos.
405 method_not_allowed Diese HTTP-Methode wird auf diesem Pfad nicht unterstützt.
409 failed-precondition Die Ressource befindet sich nicht in einem Zustand, der den Vorgang erlaubt — z. B. Bearbeitung eines eingefrorenen Links oder das Erstellen von serialisierten Codes über deine Enterprise-Zuteilung hinaus (das Limit befindet sich in der Nachricht).
429 rate_limited / resource-exhausted Per-Key-Rate-Limit erreicht (rate_limited — enthält einen retry_at-Timestamp und X-RateLimit-* Response-Header) oder ein Plan-Quota erschöpft (resource-exhausted). Backoff durchführen und erneut versuchen.
5xx internal Etwas ist bei uns schief gelaufen; sicher zu wiederholen für idempotente Lesevorgänge.

Fehler auf Transportebene (Auth, Routing, Rate-Limiting) verwenden snake_case-Codes; Fehler auf Ressourcenebene verwenden kebab-case (die Firebase-Callable-Konvention). Verzweige immer nach dem HTTP-Status, nicht nach der error-Zeichenkette.

# Eigentümerschaft

Jeder Lese- und Schreibvorgang ist auf das Konto begrenzt, zu dem der API-Schlüssel führt. Das Anfordern des Links oder der Kampagne eines anderen Kontos gibt 404 zurück (nicht 403) — wir offenbaren nicht, dass es existiert.

# Asynchrone Jobs

Batch- und serialisierte Mint-Jobs akzeptieren die Anfrage (200, queued), dann zeigen Fehler im Job-Status (status: "failed" mit einem Grund), nicht in der ursprünglichen HTTP-Response. Frage den Job immer ab.

# Verifizierung

Die öffentlichen Verifizierungs-Endpunkte geben niemals einen Fehler bei einem unbekannten Serial zurück — sie geben status: "unknown" zurück (ein gefälschter/nicht ausgegebener Code ist eine aussagekräftige Antwort, kein 404).

# Nächste Schritte