Gestisci errori e nuovi tentativi

Gli errori compaiono in tre punti distinti. Costruisci la tua gestione in base a quello che stai guardando.

1. Errori della richiesta (stato HTTP + envelope)

Validazione, autenticazione e rate limit. Sono sincroni e usano l'envelope di errore. Decidi in base a error.type per la strategia di ripetizione e a error.code per i dettagli. 429 → attendi Retry-After; 5xx → backoff esponenziale con la stessa Idempotency-Key.

2. Errori del canale (gli issues[] dell'inserzione)

La richiesta era corretta, ma il canale ha rifiutato l'inserzione in seguito, in modo asincrono. L'inserzione passa a status: "error" e issues[] contiene il messaggio del canale in testo semplice (ad esempio "You are currently in a Shop probation period…"). Sono problemi del venditore, non dell'API: mostrali al venditore.

Prima risolvi la causa, poi ritenta solo le inserzioni che falliscono con quell'errore. error_contains cerca nel messaggio di errore attuale dell'inserzione:

curl "https://api.nembol.com/rest/v1/listings?error_contains=item%20specific%20Brand" \
  -H "Authorization: Bearer $NEMBOL_API_KEY"

Poi ritenta esattamente quelle, fino a 100 per chiamata:

curl -X POST https://api.nembol.com/rest/v1/listings/batch \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "retry",
       "items": [{"product_id": "prod_66a1f0", "channel_account_id": "chac_6aa12cab"}]}'

Le inserzioni che non sono più in errore tornano skipped (not_in_error), quindi un elenco di tentativi non più aggiornato è innocuo. Per una singola inserzione, PATCH /listings/{id} con {} la risincronizza.

3. Esiti parziali (operazioni)

Le chiamate batch restituiscono un'operazione i cui results[] sono per elemento/canale. status: "partial" significa che alcuni sono riusciti. Ritenta solo le voci fallite, mai l'intero batch alla cieca.

Da sapere

• Non ritentare mai alla cieca. Filtra per il fallimento esatto (error_contains, le righe results[] fallite). Ritentare in blocco tutte le inserzioni in errore amplifica i problemi.
• La Idempotency-Key rende i nuovi tentativi gratuiti. Stessa chiave + stesso payload = risposta salvata, nessun doppio effetto.
• Nel tempo compariranno codici sconosciuti. In quel caso affidati a error.type.
• request_id è presente in ogni errore: comunicalo al supporto.

Ultimo aggiornamento il 20 ottobre 2026