Fehler-Referenz

Alle qr3.app API-Fehler folgen RFC 7807 Problem Details mit Content-Type: application/problem+json.

{
  "type": "https://docs.qr3.app/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "QR code qr_xxx not found"
}

`errors/validation`

HTTP 422 Unprocessable Entity

Die Eingabedaten haben die Schema-Validierung nicht bestanden. Die Response enthält ein errors-Array mit feldgenauen Details.

{
  "type": "https://docs.qr3.app/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request body validation failed",
  "errors": [
    { "field": "url", "message": "Invalid URL format" }
  ]
}

Ursachen: Fehlende Pflichtfelder, falsche Datentypen, Werte außerhalb des erlaubten Bereichs, ungültiges URL-Format.

`errors/bad-request`

HTTP 400 Bad Request

Der Body ist kein gültiges JSON, obwohl Content-Type: application/json gesetzt ist (z.B. Komma nach dem letzten Element, abgeschnittener oder leerer Body).

`errors/authentication`

HTTP 401 Unauthorized

Der API-Key fehlt, ist falsch formatiert, abgelaufen oder widerrufen.

Fix: Prüfe, ob der Authorization: Bearer qr3_sk_... Header vorhanden ist und der Key aktiv ist.

`errors/unauthorized`

HTTP 401 Unauthorized

Ein eingehender Webhook (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) wurde ohne gültige Signatur oder ohne gültiges Geheimnis aufgerufen. Ein fehlender oder ungültiger API-Key antwortet stattdessen mit errors/authentication.

`errors/authorization`

HTTP 403 Forbidden

Der API-Key ist gültig, aber hat nicht den erforderlichen Scope oder die nötige Berechtigung.

`errors/forbidden`

HTTP 403 Forbidden

Die Ressource existiert, gehört aber zu einem anderen Workspace oder einer anderen Organisation.

`errors/document-immutable`

HTTP 403 Forbidden

Ein DPP-Dokument, das mit is_immutable hochgeladen wurde, kann nicht gelöscht werden.

`errors/not-found`

HTTP 404 Not Found

Die angeforderte Ressource existiert nicht oder wurde gelöscht.

`errors/conflict`

HTTP 409 Conflict

Eine Ressource mit demselben eindeutigen Bezeichner existiert bereits (z.B. doppelter Slug oder Idempotency-Key-Kollision).

`errors/subscription-exists`

HTTP 409 Conflict

POST /v1/billing/checkout wurde aufgerufen, obwohl die Organisation bereits ein Abonnement hat. Den Tarif stattdessen im Abrechnungsportal wechseln.

`errors/rate-limited`

HTTP 429 Too Many Requests

Das Rate-Limit pro Minute des API-Keys wurde überschritten. Die Response enthält Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset Header.

`errors/rate-limit`

HTTP 429 Too Many Requests

Ein ressourcenspezifisches Rate-Limit wurde überschritten (z.B. 200 QR-Codes pro Tag pro Workspace).

`errors/plan-limit`

HTTP 422 Unprocessable Entity

Dein aktueller Tarif erlaubt diese Aktion nicht (z.B. Kontingent an DPPs oder dynamischen Codes ausgeschöpft, Batch zu groß, zu viele Workspaces oder Teammitglieder). Upgrade erforderlich.

`errors/invalid-file-type`

HTTP 400 Bad Request

Die hochgeladene Datei hat einen Typ, den der Endpunkt nicht annimmt, oder ihr Inhalt passt nicht zum angegebenen Content-Type.

`errors/file-too-large`

HTTP 413 Payload Too Large

Die hochgeladene Datei überschreitet die Größengrenze des Tarifs oder des Endpunkts.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

Der Upload würde den gesamten Speicher des Workspace oder des DPP überschreiten.

`errors/not-configured`

HTTP 503 Service Unavailable

Ein erforderlicher Dienst oder eine Konfiguration fehlt (z.B. Stripe nicht konfiguriert, Web Risk API-Key nicht gesetzt).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

Die URL wurde abgelehnt, weil sie von Google Web Risk als unsicher eingestuft wurde (Malware, Phishing, Social Engineering).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Reserviert für URLs, die nachträglich beim periodischen Re-Scanning als unsicher eingestuft wurden.

`errors/already-submitted`

HTTP 409 Conflict

Doppelte Einreichung — z.B. wurde bereits ein NPS-Score für diesen Workspace in diesem Monat eingereicht.

`errors/unprocessable-entity`

HTTP 422 Unprocessable Entity

Eine Admin-Aktion ist nicht zulässig (z.B. Impersonation eines anderen Superadmins). Nur die Superadmin-Endpunkte liefern diesen Typ.

`errors/request-error`

HTTP 4xx Client Error

Auffangtyp für Client-Fehler ohne genaueren Typ; der Status steht in der Antwort. Die API hat derzeit keinen bekannten Weg, der ihn liefert.

`errors/internal`

HTTP 500 Internal Server Error

Ein unerwarteter Fehler auf dem Server. Bitte wiederhole die Anfrage. Bei anhaltenden Problemen: [email protected].