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:

{
  "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.

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.
`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.

Die Fehlertypen, die ein Endpunkt zurückgeben kann, sind beim jeweiligen Endpunkt in der API-Referenz aufgeführt.

Umgang mit einem Revisionskonflikt

Um eine Transaktion zu aktualisieren oder zu löschen, 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.

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.
  }
}