Errori · documentazione TradeCatalog

Gli errori utilizzano i normali codici di stato HTTP e un corpo JSON con un code stabile che puoi verificare nel tuo codice, e un message scritto per le persone.

json

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

issues è presente solo per validation_error. Ogni problema ha path che punta al campo, con le posizioni della lista contate a partire da 0.

Codici di erroreCollegamento a questa sezione#

Stato	Codice	Cosa è successo	Cosa fare
400	`validation_error`	Un parametro di query o un campo del corpo è mancante o non valido.	Correggi i campi elencati in `issues`.
400	`invalid_json`	Il corpo non è un JSON valido.	Invia JSON con `Content-Type: application/json`.
400	`invalid_request`	La richiesta è valida ma non è consentita in questo momento, ad esempio contrassegnare un nuovo ordine come completato.	Leggi `message`; non ripetere senza modifiche.
401	`unauthorized`	Chiave API mancante, sconosciuta o revocata.	Controlla l'intestazione `Authorization: Bearer` e che la chiave sia ancora attiva.
401	`key_owner_removed`	La persona che ha creato la chiave ha lasciato il workspace.	Crea una nuova chiave da qualcuno che ha ancora accesso.
403	`insufficient_scope`	Una chiave in sola lettura ha provato a scrivere.	Usa una chiave di lettura e scrittura.
403	`read_only`	Le scritture API non sono disponibili sul piano Free attuale del workspace.	Il proprietario gestisce il piano sul sito web. Le chiavi esistenti continuano a leggere.
403	`forbidden`	La persona che ha creato la chiave non è autorizzata a farlo.	Chiedi al proprietario del workspace, o crea una chiave da qualcuno con quella autorizzazione.
403	`workspace_suspended`	TradeCatalog ha sospeso il workspace. Il proprietario è stato informato del motivo.	Le chiavi funzionano nuovamente quando la sospensione viene rimossa.
404	`not_found`	Nessun endpoint esistente, o nessun prodotto, cliente, ordine o modifica prezzo in questo workspace.	Controlla l'id, SKU o codice account.
405	`method_not_allowed`	Il percorso esiste ma non con questo metodo.	Usa un metodo dall'intestazione `Allow`.
429	`rate_limited`	Più di 120 richieste al minuto con questa chiave.	Aspetta `Retry-After` secondi (60), quindi riprova.
500	`internal_error`	Qualcosa è andato storto nel nostro lato.	Riprova con backoff. Se continua a verificarsi, contatta il supporto.

Gli ID da un altro workspace restituiscono sempre 404 not_found, mai i dati di qualcun altro.

RiprovaCollegamento a questa sezione#

Riprovare le risposte 429 e 5xx con backoff. Non riprovare altre risposte 4xx: falliranno nello stesso modo.

Tutte le scritture API sono sicure da ripetere: PUT cerca le righe per SKU o codice account, e PATCH /orders/{id} fallisce con invalid_request se l'ordine è già avanzato. Quindi un riprovare dopo un timeout di rete non duplicherà nulla.

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
}

Messaggi comuniCollegamento a questa sezione#

Richiesta	Status e messaggio
`GET /prices` con un SKU sconosciuto	`404` “Nessun prodotto con SKU HX-9999”
Qualsiasi endpoint con un cliente sconosciuto	`404` “Cliente OAK99 non trovato”
`PATCH /orders/{id}` nuovo → completato	`400` “Un ordine ricevuto non può essere contrassegnato come completato”
`PATCH /orders/{id}` annullato senza nota	`400` “Dare un motivo per l'annullamento”
`PUT /products` con lo stesso SKU due volte	`400` errore di convalida “SKU duplicato hx-8510”