Zum Inhalt springen
Dokumentationsmenü

REST API

Fehler

Die Fehlerstruktur, jeder Fehlercode und wie man sicher wiederholt.

Fehler verwenden normale HTTP-Statuscodes und einen JSON-Body mit einem stabilen code, den Sie in Ihrem Code überprüfen können, und einen message, der für Menschen geschrieben ist.

json
{
  "error": {
    "code": "validation_error",
    "message": "Some fields are invalid.",
    "issues": [
      {
        "path": "products.0.listPrice",
        "message": "Too small: expected number to be >=0"
      }
    ]
  }
}

issues ist nur für validation_error vorhanden. Jeder Fehlerpunkt path auf das Feld, wobei Listenpositionen von 0 gezählt werden.

FehlercodesLink zu diesem Abschnitt#

StatusCodeWas passiertWas zu tun
400validation_errorEin Abfrageparameter oder Feld im Body fehlt oder ist ungültig.Beheben Sie die Felder, die in issues aufgelistet sind.
400invalid_jsonDer Body ist kein gültiges JSON.Senden Sie JSON mit Content-Type: application/json.
400invalid_requestDie Anfrage ist gültig, aber nicht erlaubt, z. B. ein neuer Auftrag als abgeschlossen zu markieren.Lesen Sie message; nicht erneut versuchen, wenn nichts geändert wurde.
401unauthorizedFehlender, unbekannter oder widerrufener API-Schlüssel.Prüfen Sie den Authorization: Bearer-Header und stellen Sie sicher, dass der Schlüssel noch aktiv ist.
401key_owner_removedDie Person, die den Schlüssel erstellt hat, hat den Workspace verlassen.Erstellen Sie einen neuen Schlüssel von jemandem, der noch Zugriff hat.
403insufficient_scopeEin Schreibschlüssel versuchte zu schreiben.Verwenden Sie einen Read & write-Schlüssel.
403read_onlyAPI-Schreibvorgänge sind auf dem aktuellen Free-Plan des Workspaces nicht verfügbar.Der Eigentümer verwaltet den Plan auf der Website. Bestehende Schlüssel können weiterhin lesen.
403forbiddenDie Person, die den Schlüssel erstellt hat, ist nicht berechtigt, dies zu tun.Fragen Sie einen Workspace-Besitzer oder erstellen Sie einen Schlüssel von jemandem mit dieser Berechtigung.
403workspace_suspendedTradeCatalog hat den Workspace gesperrt. Der Eigentümer wurde per E-Mail über den Grund informiert.Schlüssel funktionieren wieder, sobald die Sperrung aufgehoben wird.
404not_foundKeine solche Endpunkt, oder kein solches Produkt, Kunde, Auftrag oder Preisanpassung in diesem Workspace.Prüfen Sie die ID, SKU oder Kontonummer.
405method_not_allowedDer Pfad existiert, aber nicht mit dieser Methode.Verwenden Sie eine Methode aus dem Allow-Header.
429rate_limitedMehr als 120 Anfragen pro Minute mit diesem Schlüssel.Warten Sie Retry-After Sekunden (60), dann erneut versuchen.
500internal_errorEtwas ist auf unserer Seite schiefgelaufen.Erneut mit Backoff versuchen. Wenn es weiterhin auftritt, wenden Sie sich an den Support.

IDs aus einem anderen Arbeitsbereich geben immer 404 not_found zurück, nie Daten von jemand anderem.

WiederholenLink zu diesem Abschnitt#

Wiederholen Sie 429 und 5xx-Antworten mit Backoff. Wiederholen Sie keine anderen 4xx-Antworten: Sie werden auf die gleiche Weise fehlschlagen.

Alle API-Schreibvorgänge können sicher wiederholt werden: PUT sucht Zeilen anhand der SKU oder des Kontocodes, und PATCH /orders/{id} schlägt fehl mit invalid_request, wenn die Bestellung bereits weitergegangen ist. Daher wird bei einer Wiederholung nach einem Netzwerk-Time-out nichts dupliziert.

js
async function api(path, init = {}, attempt = 0) {
  const res = await fetch(`https://tradecatalog.app/api/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}`,
      'Content-Type': 'application/json',
      ...init.headers,
    },
  })
  if ((res.status === 429 || res.status >= 500) && attempt < 5) {
    const wait = Number(res.headers.get('Retry-After')) || 2 ** attempt
    await new Promise((resolve) => setTimeout(resolve, wait * 1000))
    return api(path, init, attempt + 1)
  }
  const body = await res.json()
  if (!res.ok) {
    const error = new Error(`${body.error.code}: ${body.error.message}`)
    error.status = res.status
    error.code = body.error.code
    error.issues = body.error.issues
    throw error
  }
  return body
}

Häufige NachrichtenLink zu diesem Abschnitt#

AnfrageStatus und Nachricht
GET /prices mit einer unbekannten SKU404 „Kein Produkt mit SKU HX-9999“
Jeder Endpunkt mit einem unbekannten Kunden404 „Kunde OAK99 nicht gefunden“
PATCH /orders/{id} neu → abgeschlossen400 „Eine empfangene Bestellung kann nicht als abgeschlossen markiert werden“
PATCH /orders/{id} auf storniert mit keinem Hinweis400 „Geben Sie einen Grund für die Stornierung an“
PUT /products mit der gleichen SKU zweimal400 Validierungsfehler „Doppelte SKU hx-8510“