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.
{
"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#
| Status | Code | Was passiert | Was zu tun |
|---|---|---|---|
| 400 | validation_error | Ein Abfrageparameter oder Feld im Body fehlt oder ist ungültig. | Beheben Sie die Felder, die in issues aufgelistet sind. |
| 400 | invalid_json | Der Body ist kein gültiges JSON. | Senden Sie JSON mit Content-Type: application/json. |
| 400 | invalid_request | Die 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. |
| 401 | unauthorized | Fehlender, unbekannter oder widerrufener API-Schlüssel. | Prüfen Sie den Authorization: Bearer-Header und stellen Sie sicher, dass der Schlüssel noch aktiv ist. |
| 401 | key_owner_removed | Die Person, die den Schlüssel erstellt hat, hat den Workspace verlassen. | Erstellen Sie einen neuen Schlüssel von jemandem, der noch Zugriff hat. |
| 403 | insufficient_scope | Ein Schreibschlüssel versuchte zu schreiben. | Verwenden Sie einen Read & write-Schlüssel. |
| 403 | read_only | API-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. |
| 403 | forbidden | Die 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. |
| 403 | workspace_suspended | TradeCatalog hat den Workspace gesperrt. Der Eigentümer wurde per E-Mail über den Grund informiert. | Schlüssel funktionieren wieder, sobald die Sperrung aufgehoben wird. |
| 404 | not_found | Keine solche Endpunkt, oder kein solches Produkt, Kunde, Auftrag oder Preisanpassung in diesem Workspace. | Prüfen Sie die ID, SKU oder Kontonummer. |
| 405 | method_not_allowed | Der Pfad existiert, aber nicht mit dieser Methode. | Verwenden Sie eine Methode aus dem Allow-Header. |
| 429 | rate_limited | Mehr als 120 Anfragen pro Minute mit diesem Schlüssel. | Warten Sie Retry-After Sekunden (60), dann erneut versuchen. |
| 500 | internal_error | Etwas 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.
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#
| Anfrage | Status und Nachricht |
|---|---|
GET /prices mit einer unbekannten SKU | 404 „Kein Produkt mit SKU HX-9999“ |
| Jeder Endpunkt mit einem unbekannten Kunden | 404 „Kunde OAK99 nicht gefunden“ |
PATCH /orders/{id} neu → abgeschlossen | 400 „Eine empfangene Bestellung kann nicht als abgeschlossen markiert werden“ |
PATCH /orders/{id} auf storniert mit keinem Hinweis | 400 „Geben Sie einen Grund für die Stornierung an“ |
PUT /products mit der gleichen SKU zweimal | 400 Validierungsfehler „Doppelte SKU hx-8510“ |