> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Every page is available as Markdown by appending `.md` to its URL; this page is [Markdown](https://www.boxhero.io/docs/de/developers/api/errors.md).

# Fehler

> Verstehen Sie das Fehlerobjekt, das die BoxHero API zurückgibt, und wie Sie Fehler in Ihrem Code behandeln.

Wenn eine Anfrage fehlschlägt, antwortet die BoxHero API mit einem HTTP-Fehlerstatus und einem einzelnen JSON-Fehlerobjekt:

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "type": "/errors/not-found",
  "title": "No item with id 12345 found in this team.",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "instance": "/items/12345"
}
```

## Felder

| Feld | Beschreibung |
| --- | --- |
| `id` | Eindeutige ID des Fehlers: `ex_` gefolgt von 32 hexadezimalen Zeichen in Kleinbuchstaben. Geben Sie sie an, wenn Sie den Support kontaktieren. |
| `type` | Stabiler, maschinenlesbarer Fehlercode. Verzweigen Sie in Ihrem Code anhand dieses Werts, nicht anhand von `title`. |
| `title` | Für Menschen lesbare Zusammenfassung auf Englisch. Der Wortlaut kann sich ändern. |
| `correlationID` | ID der Anfrage: `rq_` gefolgt von 32 hexadezimalen Zeichen in Kleinbuchstaben, identisch mit dem Antwort-Header `X-Correlation-Id`. Damit finden wir Ihre Anfrage in unseren Logs. |
| `instance` | Die Ressource, bei der der Fehler auftrat, zum Beispiel `/items/12345`. Der Pfad hat kein Präfix `/v1`. |
| `code` | Genauerer Grund des Fehlers, zum Beispiel `tx-modify-revision-mismatch`. Nicht immer vorhanden. Verzweigen Sie zuerst anhand von `type` und für eine feinere Behandlung dann anhand von `code`. |
| `errors` | Details auf Feldebene, vorhanden in Antworten mit `/errors/invalid-request` (`400`). Jeder Eintrag hat einen `path`, der das ungültige Feld angibt, und eine für Menschen lesbare `message`. |

Manche Fehler enthalten außerdem die id der betroffenen Ressource, etwa `item_id` oder `order_id`, als zusätzliche Felder auf oberster Ebene.

> **Note**
>
> Sie können einen eigenen Anfrage-Header `X-Correlation-Id` senden, um Ihre Traces mit unseren zu verknüpfen. Derselbe Wert kommt in der Antwort und in `correlationID` zurück.

## Häufige Statuscodes

| Status | Bedeutung | Was zu tun ist |
| --- | --- | --- |
| `400` | Die Anfrage ist ungültig, oder der Modus des Teams unterstützt diesen Endpunkt nicht | Korrigieren Sie die Anfrage – `errors` listet die ungültigen Felder auf. Wiederholen Sie sie nicht unverändert. |
| `401` | Der API-Token fehlt oder ist ungültig | Prüfen Sie den Header `Authorization`. Siehe [Authentifizierung](https://www.boxhero.io/docs/de/developers/api/authentication). |
| `403` | BoxHero hat die Änderung abgelehnt – zum Beispiel, weil sie gegen eine Bestandsregel verstößt oder die gesendete `revision` veraltet ist | Prüfen Sie `code`, um den Grund zu erfahren. Korrigieren Sie die Anfrage oder rufen Sie die neuesten Daten ab, bevor Sie es erneut versuchen. |
| `404` | Die Ressource existiert in diesem Team nicht oder wurde gelöscht | Prüfen Sie die id. Wiederholen Sie die Anfrage nicht unverändert. |
| `429` | Zu viele Anfragen | Warten Sie und versuchen Sie es erneut. Siehe [Ratenbegrenzung](https://www.boxhero.io/docs/de/developers/api/rate-limiting). |

Die Fehlertypen, die ein Endpunkt zurückgeben kann, sind beim jeweiligen Endpunkt in der [API-Referenz](https://www.boxhero.io/docs/de/developers/api/reference) aufgeführt.

## Umgang mit einem Revisionskonflikt

Um eine Transaktion zu [aktualisieren](https://www.boxhero.io/docs/de/developers/api/reference/transactions/update-transaction) oder zu [löschen](https://www.boxhero.io/docs/de/developers/api/reference/transactions/delete-transaction), senden Sie die neueste `revision`, die Ihnen bekannt ist. Hat jemand anderes die Transaktion zwischenzeitlich geändert, lehnt die API die Anfrage mit `403` ab, wobei `code` auf `tx-modify-revision-mismatch` gesetzt ist. Verzweigen Sie anhand von `code`: Rufen Sie die Transaktion erneut ab, prüfen Sie die Änderung und versuchen Sie es mit der neuen `revision` erneut.

```js
const res = await fetch(`https://rest.boxhero-app.com/v1/transactions/${id}`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.BOXHERO_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ revision, memo: "Recounted" }),
});

if (res.status === 403) {
  const error = await res.json();
  if (error.code === "tx-modify-revision-mismatch") {
    // Fetch the transaction again, check the change, then retry with its new revision.
  }
}
```