Tradotta dall'inglese. In caso di differenze fa fede la pagina in inglese. Leggi in inglese
Errori
Il formato degli errori, tutti i codici di errore e cosa fare per ciascuno.
Ogni risposta di errore ha la stessa forma:
{
"error": {
"type": "invalid_request_error",
"code": "photo_required_for_channel",
"message": "Product 66a1… has no images: channel \"etsy\" requires at least one image. Add an image, then publish again.",
"param": null,
"doc_url": "https://developers.nembol.com/docs/getting-started/errors#photo_required_for_channel"
},
"request_id": "req_9f83…"
}type: una di quattro famiglie (vedi sotto). Usalo per decidere la logica di retry.code: stringa stabile, leggibile dalle macchine. Usalo per la gestione dei casi specifici.message: leggibile da una persona, in inglese, ti dice come risolvere. Non analizzarlo mai.param: il campo che ha causato l'errore di validazione (es.variants[2].price).request_id: includilo quando contatti il supporto.
Tipi di errore
Codici comuni
| Codice | HTTP | Significato |
|---|---|---|
invalid_api_key | 401 | Chiave mancante, malformata, revocata o rigenerata |
insufficient_scope | 403 | Alla chiave manca il permesso per questo endpoint |
plan_not_eligible | 403 | Il piano del negozio non include l'accesso all'API (durante la prova: funzionano solo le chiavi di test) |
product_not_found / order_not_found / variant_not_found / listing_not_found / action_not_found / operation_not_found / event_not_found / import_not_found / channel_account_not_found / channel_connection_not_found / ignored_listing_not_found / webhook_endpoint_not_found / redirect_url_not_found / promotion_not_found / discount_not_found / bundle_not_found / notification_not_found | 404 | Nessuna risorsa di questo tipo in questo negozio. listing_not_found compare anche per singolo elemento nei risultati batch delle inserzioni |
validation_failed | 422 | Vedi param e message |
invalid_json | 400 | Il body non è un JSON valido (manca una virgoletta, una virgola o una parentesi). Nulla è stato letto o modificato |
payload_too_large | 413 | Il body supera i 25 MB. Invia le immagini come URL o tramite POST /files, oppure dividi il batch |
unsupported_encoding | 415 | Il charset o la codifica del body non sono supportati. Invia JSON in UTF-8 (gzip va bene) |
subscription_inactive | 402 | L'abbonamento Nembol del negozio non è attivo: non si possono collegare o scollegare canali (POST /channel_connections, POST /channel_accounts/{id}/disconnect). Lo stesso codice può arrivare su return_url quando il link viene aperto |
photo_required_for_channel | 422 | Pubblicazione di un prodotto senza immagini su un canale che le richiede |
billing_managed_by_nembol | 409 | Un link di fatturazione su un negozio fatturato direttamente da Nembol (billing_source: "manual"): le modifiche passano da billing@nembol.com |
no_items_applied | 422 | POST /inventory/batch e POST /products/batch: nessun elemento è stato applicato (ogni SKU è sconosciuto, ambiguo, su un prodotto da controllare, oppure non valido). I motivi sono in error.details.rejected_items; nulla è cambiato |
image_unreachable | 422 | Non è stato possibile scaricare un url di immagine (l'host ha rifiutato o l'URL è errato; param indica quale immagine). Usa un URL pubblico o invia il file come base64 |
channel_not_connected | 422 | Pubblicazione/rimozione, o una promozione, su un canale che il negozio non ha collegato |
not_supported_for_channel | 422 | Questo endpoint funziona solo per alcuni canali. Il messaggio li elenca |
setting_not_supported | 422 | Questa impostazione non esiste su questo account canale. Il suo array writable elenca cosa si può modificare |
trial_publish_limit | 403 | Raggiunto il limite di pubblicazioni della prova su questo canale. Compare anche per singolo elemento nei risultati batch delle inserzioni. Abbonati per pubblicare di più |
sku_not_found / sku_ambiguous | 422 | Elemento del batch rifiutato (/inventory/batch, /products/batch): SKU sconosciuto, oppure uno SKU presente su più varianti (error.details.product_ids le elenca; nulla è stato scritto). Correggi il duplicato o aggiorna per id |
images_unsupported_on_batch_update | per elemento | L'elemento del batch corrisponde a un prodotto esistente ma ha inviato images. Aggiorna le sue immagini con PATCH /products/{id} |
file_too_large / unsupported_file_type | 422 | Un'immagine (POST /files, o images[] come base64 o url) supera i 10 MB, oppure non è JPEG, PNG, WebP o GIF, ad esempio un URL che risponde con una pagina HTML. param indica quale immagine |
idempotency_key_reused | 409 | Stessa Idempotency-Key con un payload diverso |
idempotency_key_in_flight | 409 | La prima richiesta con questa Idempotency-Key è ancora in esecuzione. Riprova tra poco |
precondition_failed | 412 | expected_updated_at non corrisponde. Rileggi e riprova |
product_still_listed | 422 | Eliminazione rifiutata: il prodotto ha ancora inserzioni attive. Rimuovilo prima dai canali |
order_not_fulfillable | 422 | L'ordine è annullato/rimborsato e non può essere segnato come spedito |
channel_notification_unsupported | 422 | Questo canale non può ricevere notifiche di spedizione. Riprova con notify_channel: false |
overrides_not_supported | 422 | Per ora su un'inserzione si possono impostare solo overrides.title / overrides.description. Un body vuoto risincronizza |
listing_not_delistable | 422 | Le inserzioni importate/collegate sono gestite dal canale |
listing_operation_in_progress | 409 | Attendi l'operazione in corso, poi riprova |
not_started | per elemento | Risultato di un'operazione: il job sul canale non è potuto partire perché un'altra operazione ha preso l'inserzione. Riprova |
no_price / price_below_minimum | per elemento | Risultato di un adeguamento prezzi: il prodotto non ha varianti con prezzo, oppure il nuovo prezzo scenderebbe sotto il minimo. Nulla è cambiato per quel prodotto |
channel_error | n/d | (negli issues[] di un'inserzione) il canale ha rifiutato l'ultima scrittura. Il messaggio è l'errore del canale. Filtra con error_contains |
import_not_supported | 422 | Non si possono importare prodotti da questo canale |
import_already_running | 409 | Un'importazione da questo account canale, o un'importazione CSV, è già in coda o in corso. Attendi che finisca |
import_still_running / import_already_undone | 409 | Annullamento importazione: l'importazione non è ancora terminata, oppure è già stata annullata |
promotion_reaches_nothing | 422 | Promozioni: nessuno dei prodotti è pubblicato sui canali scelti, quindi non sconterebbe nulla. Pubblicali prima, oppure salvala come bozza |
promotion_conflict | 409 | Alcuni prodotti sono già in un'altra promozione attiva. Vedi error.details.product_ids e promotion_ids |
promotion_limit_reached | 403 | Basic (e una prova gratuita) esegue una promozione alla volta (attiva o programmata; le bozze non contano); da Pro in su non c'è limite. Vedi limits.running_promotions in GET /billing. Ferma l'altra o passa a un piano superiore |
unknown_channel | 422 | Promozioni: un canale in channels su cui le promozioni non funzionano. Il messaggio lo indica ed elenca quelli validi |
discount_exceeds_price | 422 | Promozioni: uno sconto fisso non è inferiore a un prezzo coperto. error.details indica product_id, variant_id, channel e price |
promotion_running / promotion_not_running / promotion_reverting | 409 | Promozioni: modifica o eliminazione mentre è in corso (fermala prima); stop su una che non è in corso; eliminazione mentre i prezzi sui canali sono ancora in fase di ripristino (riprova tra poco) |
plan_upgrade_required | 403 | Storefront: il piano del negozio non include questa funzione |
code_exists | 409 | Storefront: esiste già uno sconto con questo codice (param: code) |
transition_not_allowed | 409 | Ordine dello storefront: l'ordine non può passare dallo stato attuale a quello richiesto |
already_refunded / order_not_paid | 409 | Rimborso di un ordine dello storefront: non resta nulla da rimborsare, oppure l'ordine non è mai stato pagato. Risposta data prima di qualsiasi conferma |
stripe_refund_failed / paypal_refund_failed | 502 | Rimborso di un ordine dello storefront: il fornitore di pagamento lo ha rifiutato; il messaggio ne riporta il motivo |
sku_required / title_required | per elemento | All'elemento del batch manca lo SKU su cui fare il match / un titolo con cui crearlo |
route_not_found | 404 | Questo endpoint non esiste. Controlla il riferimento |
rate_limit_exceeded | 429 | Bucket vuoto. Rispetta Retry-After |
write_quota_exceeded | 429 | Raggiunta la quota giornaliera di scritture sui canali |
internal_error | 500 | Qualcosa è andato storto da parte nostra. Riprova con backoff; indica il request_id se il problema persiste |
channel_unavailable | 502 | Il canale non ha risposto o ha restituito un errore. Riprova più tardi |
confirmation_required | 409 | Azione irreversibile: mostra confirmation.summary, poi ripeti la stessa richiesta con Nembol-Confirmation. Vedi Annullamento e conferme |
confirmation_invalid | 409 | Il token di conferma è già usato, scaduto o relativo a un'altra richiesta. Ne trovi uno nuovo nella risposta |
undo_conflict | 409 | Nulla è stato annullato: ogni valore è stato modificato di nuovo nel frattempo. Vedi error.details |
action_already_undone | 409 | L'azione è già stata annullata |
not_reversible | 422 | L'azione non può essere annullata; il messaggio indica cosa fare invece |
undo_window_expired | 422 | Le azioni si possono annullare per 30 giorni |
product_not_deleted | 409 | Ripristino chiamato su un prodotto che non è eliminato |
product_requires_attention | 409 | Il prodotto è to_verify: risolvilo (POST /products/{id}/resolve o un'unione) prima di scrivere sulle sue inserzioni |
product_not_requiring_attention | 409 | Risoluzione chiamata su un prodotto che non è to_verify |
resolution_not_applicable | 409 | Questa risoluzione non si adatta al requires_attention.reason del prodotto |
still_requires_attention | 409 | recheck: l'impostazione del canale non è ancora corretta. Vedi error.details.reason |
confirm_different | 409 | Unione: i prodotti non sembrano simili. Controlla error.details.product_ids, poi invia confirm_different: true |
same_channel_account | 422 | Unione: due prodotti sono online sullo stesso account canale. Vedi error.details.channels |
variants_differ | 422 | Unione: le varianti non corrispondono. Abbinale con variant_maps usando error.details.matching |
invalid_choices / too_few / too_many | 422 | Unione: una voce di choices non è valida, oppure i prodotti non sono tra 2 e 10 |
product_merged | 409 | Ripristino rifiutato: il prodotto è stato unito. Annulla invece l'unione |
not_a_partner | 403 | Nembol-Account o endpoint partner usati da un negozio che non è partner |
not_on_a_sub_account | 400 | Hai inviato Nembol-Account a un endpoint partner (/accounts, /partner/*). Questi operano sul tuo account partner: chiamali senza l'header |
sandbox_limit | 409 | Un partner in sandbox ha raggiunto il numero massimo di aziende aperte. Chiudine prima una |
plan_too_small | 409 | L'azienda ha più prodotti o account canale di quanti ne consenta il nuovo piano |
account_not_found | 404 | Nessuna azienda con questo id per la tua chiave partner |
billed_by_partner | 409 | /billing chiamato all'interno di un'azienda: le aziende vengono fatturate al partner |
billing_managed_elsewhere | 422 | Il negozio è fatturato tramite Shopify, Wix o WooCommerce.com. Cambia piano, disdici o aggiorna il pagamento lì |
return_url_not_allowed | 422 | return_url deve iniziare con un URL registrato per questo negozio (POST /redirect_urls) |
plan_limits_exceeded | 422 | Cambio piano: il negozio usa più di quanto consenta il piano di destinazione. Riduci l'utilizzo o scegli un piano più grande |
no_payment_method_yet / no_subscription_yet | 422 | Il negozio non ha ancora una fatturazione Stripe. Abbonati prima con POST /billing/plan_change_link |
already_canceled / already_canceling / nothing_to_cancel | 422 | Disdetta: l'abbonamento è già disdetto, termina già a fine periodo, oppure non c'è nulla da disdire (prova, nessun abbonamento Stripe) |
trial_not_available | 422 | Il negozio non può riavviare una prova |
billing_provider_error | 502 | Stripe o PayPal non hanno restituito una pagina. 409 quando PayPal rifiuta la modifica. Riprova più tardi |
billing_links_unavailable | 503 | I link di fatturazione non sono ancora disponibili. Gestisci l'abbonamento dalla dashboard Nembol |
account_suspended / account_closed | 409 | Scritture su un'azienda sospesa (fattura partner scaduta) o chiusa |
product_limit_reached | 409 | Raggiunto il limite di prodotti del piano dell'azienda. Cambia il suo piano o elimina dei prodotti |
channel_slots_full | 422 | Nessuno slot libero per questo canale. Scollega prima un account |
plan_channel_not_included | 403 | Il piano del negozio non include questo canale. Passa a un piano superiore per collegarlo |
channel_not_disconnectable | 422 | Il negozio paga il suo abbonamento Nembol tramite questo account, quindi non può essere scollegato |
connection_not_awaiting_choice | 409 | choose su una connessione che non è needs_choice |
choice_expired | 410 | È passata più di un'ora da quando il venditore ha effettuato l'accesso. Crea un nuovo link |
link_expired / link_already_used | n/d | (su return_url) il link di collegamento è scaduto o è già stato usato. Creane uno nuovo |
different_channel_account | n/d | (in connection.error e su return_url) il venditore ha effettuato l'accesso a un negozio diverso da quello da ricollegare (channel_account_id, oppure un account scollegato che viene riportato: reconnects_shop). Nulla è cambiato. Accedi a quel negozio, oppure collega quello nuovo con new_account: true (senza channel_account_id) |
channel_login_failed | n/d | (su return_url e in connection.error) l'accesso al canale non è partito o non si è completato. Crea un nuovo link |
channel_credentials_rejected | n/d | (in connection.error) il canale ha rifiutato le credenziali inviate |
plan_not_eligible / subscription_inactive / slot_no_longer_available | n/d | (su return_url, errore di connessione) il negozio non può più collegare quel canale |
no_account_to_connect | n/d | (errore di connessione) l'account canale del venditore non ha nulla che Nembol possa collegare |
Nuovi codici vengono aggiunti nel tempo; gestisci i codici sconosciuti ricadendo su type.
Ultimo aggiornamento il 21 ottobre 2026