> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fehler

> Fehlerformat und Fehlercodes der GetQR API.

> [!NOTE]
>
> Die GetQR API befindet sich in der Beta-Phase und steht ausgewählten Workspaces zur Verfügung. Details können sich bis zur allgemeinen Veröffentlichung noch ändern.

Die GetQR API verwendet die üblichen HTTP-Statuscodes. Erfolgreiche Anfragen liefern `2xx`. Fehlgeschlagene Anfragen liefern `4xx` oder `5xx` mit einem JSON-Body, der das Problem beschreibt.

## Fehlerformat

Jeder Fehler hat denselben Aufbau: einen stabilen Code, eine lesbare Meldung und einen Link zur Beschreibung dieses Codes.

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized: Invalid API key.",
    "doc_url": "https://getqr.com/account/api-docs#error-unauthorized"
  }
}
```

**error.code** `string` *required*

Stabiler, maschinenlesbarer Fehlercode. Werten Sie in Ihrem Code diesen statt der Meldung aus. Siehe [Fehlercodes](#fehlercodes).

**error.message** `string` *required*

Lesbare Beschreibung des Problems. Der Wortlaut kann sich ändern.

**error.doc\_url** `string` *required*

Link zur Beschreibung des Fehlercodes in der API-Dokumentation in Ihrem GetQR-Konto.

## Fehlercodes

| Code | HTTP-Status | Wann er auftritt |
| - | - | - |
| `bad_request` | 400 | Die Anfrage ist fehlerhaft: Der Body ist kein gültiges JSON, dem `Authorization`-Header fehlt das Präfix `Bearer `, oder die Aktion ist im aktuellen Zustand der Ressource nicht erlaubt (zum Beispiel das Abbrechen einer abgeschlossenen Massenerstellung). |
| `unauthorized` | 401 | Der API-Schlüssel fehlt oder ist ungültig, zum Beispiel weil er neu erzeugt wurde. |
| `forbidden` | 403 | Das Abonnement des Workspace-Admins ist nicht aktiv, oder Ihre Rolle im Workspace erlaubt diese Aktion nicht. |
| `exceeded_limit` | 403 | Sie haben ein Tariflimit erreicht. Im Tarif Single QR: Sie erstellen oder duplizieren einen QR-Code, obwohl der Workspace bereits einen hat, oder starten eine Massenerstellung. |
| `not_found` | 404 | Die Ressource existiert nicht oder gehört nicht zu Ihrem Workspace, der Endpunkt existiert nicht, oder die API ist für Ihren Workspace nicht freigeschaltet. |
| `method_not_allowed` | 405 | Der Endpunkt existiert, akzeptiert diese HTTP-Methode aber nicht. Der `Allow`-Header listet die zulässigen Methoden auf. |
| `conflict` | 409 | Die Anfrage kollidiert mit vorhandenen Daten: Der Slug des Kurzlinks ist vergeben, eine Anfrage mit demselben `Idempotency-Key` läuft noch, ein Zeitplan überschneidet sich mit einem bestehenden, oder ein Archiv der Massenerstellung ist noch nicht fertig. |
| `invite_pending` | 409 | Sie wurden in den Workspace eingeladen, sind aber noch nicht beigetreten. Anfragen mit API-Schlüssel liefern diesen Code nicht: Der Workspace des Schlüssels ist immer einer, dem Sie angehören. |
| `invite_expired` | 410 | Ihre Einladung in den Workspace ist abgelaufen. Anfragen mit API-Schlüssel liefern diesen Code aus demselben Grund nicht. |
| `unprocessable_entity` | 422 | Der Body oder die Query-Parameter haben die Validierung nicht bestanden. Die Meldung nennt das Feld und das Problem. Siehe [Validierungsfehler](#validierungsfehler). |
| `rate_limit_exceeded` | 429 | Der API-Schlüssel hat seine Anfragen für das aktuelle Zeitfenster aufgebraucht. Siehe [Ratenbegrenzungen](https://docs.getqr.com/de/api/rate-limits.md). |
| `internal_server_error` | 500 | Auf unserer Seite ist etwas schiefgelaufen. Versuchen Sie es später erneut und wenden Sie sich an den Support, wenn das Problem bestehen bleibt. |

## Validierungsfehler

Bestehen der Body oder die Query-Parameter die Validierung nicht, antwortet die API mit `422`. Die Meldung beschreibt das erste ungültige Feld im Format `<issue>: <field>: <details>`:

```json theme={null}
{
  "error": {
    "code": "unprocessable_entity",
    "message": "too_big: pageSize: Max page size is 100.",
    "doc_url": "https://getqr.com/account/api-docs#error-unprocessable_entity"
  }
}
```

Verschachtelte Felder werden in Punktnotation angegeben, zum Beispiel `link.url`.

## Fehler behandeln

* Verzweigen Sie anhand von `error.code`, nicht anhand von `error.message`.
* Wiederholen Sie `4xx`-Fehler nicht unverändert: Korrigieren Sie zuerst die Anfrage. Ausnahmen sind ein `409` für eine noch laufende Anfrage und `429`.
* Warten Sie bei `429` so viele Sekunden, wie der `Retry-After`-Header angibt. Siehe [Ratenbegrenzungen](https://docs.getqr.com/de/api/rate-limits.md#wenn-sie-das-limit-überschreiten).
* Wiederholen Sie `5xx`-Fehler mit exponentiellem Backoff.

## Häufige Probleme

> [accordion] Jede Anfrage liefert 404 "This endpoint is not available."
>
> Die API befindet sich in der Beta-Phase und ist für Ihren Workspace noch nicht freigeschaltet.

> [accordion] 404 "This endpoint does not exist."
>
> Der Pfad ist falsch. Gleichen Sie ihn mit den Endpunktseiten ab und prüfen Sie, ob er mit `/api/v1/` beginnt.

> [accordion] 403 "Access denied: This account does not have an active subscription."
>
> Das Abonnement des Workspace-Admins ist abgelaufen. Der API-Schlüssel funktioniert wieder, sobald der Admin erneut ein Abonnement abschließt.

> [accordion] 403 "API access is not available for this role."
>
> Ihre Rolle im Workspace ist Viewer. Nur der Workspace-Admin und Editoren können die API verwenden.

## Wie geht es weiter?

> [card] [Ratenbegrenzungen](https://docs.getqr.com/de/api/rate-limits.md)

> [card] [Authentifizierung](https://docs.getqr.com/de/api/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.