Envelope dell'errore
{
"error": {
"code": "asset_not_found",
"message": "No asset with id 42 for this shop",
"status": 404,
"request_id": "req_..."
}
}Includi il request id quando contatti l'assistenza.
Codici di errore comuni
| HTTP | Codice | Significato |
|---|---|---|
| 400 | invalid_request | JSON malformato o campo mancante. |
| 400 | idempotency_key_required | Richiesta di scrittura priva di Idempotency-Key. |
| 401 | unauthorized | Token mancante, non valido, sconosciuto o revocato. |
| 402 | plan_required | Il negozio è sul piano Free. L'API esterna richiede un piano a pagamento. Per una notifica di aggiornamento prodotto significa anche che l'abbonamento del negozio non è attivo, e una campagna interrotta per uno dei due motivi dopo essere stata messa in coda riporta error: plan_required su GET /notifications/{id}. |
| 403 | forbidden | L'API esterna è disattivata (l'interruttore di emergenza globale), alla chiave API manca un ambito di accesso di cui la richiesta ha bisogno oppure, sulle route delle notifiche di aggiornamento prodotto, Alva ha disattivato queste notifiche come freno di emergenza. Contattaci se una chiave con gli ambiti corretti la riceve. |
| 403 | notifications_suspended | Le notifiche di aggiornamento prodotto sono sospese per questo negozio a seguito di reclami di spam su campagne precedenti. Nessun nuovo tentativo serve — contatta l'assistenza. |
| 404 | asset_not_found, mapping_not_found, order_not_found, category_not_found, job_not_found | La risorsa non esiste o appartiene a un altro negozio. |
| 404 | notification_not_found | La notifica di aggiornamento prodotto non esiste o appartiene a un altro negozio. |
| 409 | idempotency_conflict | La stessa chiave è stata riutilizzata con una richiesta diversa. |
| 409 | stamping_in_progress | Il reinvio è bloccato finché la timbratura del PDF è in sospeso. |
| 409 | delivery_not_yet_released | Il prodotto ha un ritardo di consegna dei download configurato e i file dell'acquirente non sono ancora sbloccati. error.details.release_at è l'istante ISO 8601 dello sblocco; il merchant può rilasciare l'ordine in anticipo con l'endpoint grant-downloads. |
| 409 | notification_not_cancellable | Solo una notifica di aggiornamento prodotto in coda può essere annullata. Questa ha già iniziato l'invio, è terminata, è fallita o è stata annullata — error.details.status dice quale. |
| 409 | app_not_installed | Alva non ha una sessione Shopify attiva per il negozio, di solito perché l'app è stata disinstallata, quindi una richiesta che ha bisogno di Shopify non può essere eseguita — una scrittura di mappatura, o una notifica di aggiornamento prodotto la cui nota fa riferimento a un metacampo o che invia variant_ids. Apri o reinstalla l'app nell'admin di Shopify, poi riprova. |
| 409 | multiple_mappings_match | Un id Shopify corrisponde a più di una mappatura, quindi Alva non può capire quale intendi. Su POST /products/{id}/notifications, error.details.ambiguous_variant_ids elenca le varianti richieste servite da più di una mappatura. |
| 409 | personalized_product | Il prodotto è personalizzato. La personalizzazione vale per l'intero prodotto, quindi POST /mappings con shopify_variant_ids non può aggiungergli una mappatura specifica per variante (non viene scritto nulla), e POST /products/{id}/notifications non può notificare i suoi acquirenti, perché ogni ordine ha il proprio file. |
| 422 | storage_quota_exceeded | Il caricamento o l'importazione supererebbe la quota di archiviazione. |
| 422 | key_limit_reached | Il negozio ha già il massimo di 25 chiavi API attive; revocane prima una. |
| 422 | withdrawal_consent_required | Il negozio ha attivato il consenso al diritto di recesso UE e l'ordine non ha ancora un record di consenso; gli URL di download vengono emessi non appena il cliente acconsente. |
| 422 | email_disabled | Le email ai clienti sono disattivate nelle impostazioni email dell'app. Restituito da un reinvio dell'email di un ordine, da POST /orders/{id}/assignments con send_email: true (non viene creato nulla), da POST /products/{id}/notifications e come esito di notify_customers in una scrittura di mappatura (la mappatura in sé viene comunque salvata). Attivale, poi riprova. |
| 422 | invalid_message | La nota di aggiornamento prodotto ha violato una regola: vuota, troppo lunga (anche una volta compilate le sue variabili), una variabile sconosciuta o non chiusa, più di cinque metacampi diversi, un link o un indirizzo email (anche all'interno del valore di un metacampo), oppure un metacampo mancante, troppo lungo o di un tipo che non può essere mostrato in un'email. error.details.errors[] indica ogni regola; error.details.max_length è il limite (2.000). Non è stato inviato né scritto nulla. In una scrittura di mappatura con notify_customers, solo le regole sul testo stesso della nota rifiutano la scrittura; un problema di metacampo viene riportato in data.notification dopo il salvataggio della mappatura. |
| 422 | no_downloadable_content | Nessuna mappatura interessata ha file, pack o link da annunciare; le mappature solo chiavi e personalizzate non possono essere oggetto di un aggiornamento prodotto. Con variant_ids, quando il prodotto ha un'altra mappatura che potrebbe essere notificata, error.details.mapping_ids indica le mappature a cui sono state risolte quelle varianti. |
| 422 | no_eligible_recipients | Nessuno a cui scrivere: nessun acquirente delle mappature interessate è iscritto. error.details.opted_out_count dice quanti si sono disiscritti. Una mappatura appena creata non ha ancora acquirenti. |
| 429 | rate_limited | È stato raggiunto il limite di chiavi API o di reinvii dell'ordine. |
| 429 | notification_cooldown | Una notifica di aggiornamento prodotto per prodotto ogni 7 giorni, attraverso tutte le sue varianti e ogni origine — oppure una campagna per il prodotto è ancora in coda o in invio. Non è il token bucket: Retry-After può arrivare a sette giorni e error.details.next_available_at è l'istante in cui il prodotto torna libero. Non riprovare automaticamente — pianifica la chiamata successiva a next_available_at. Annullare una campagna non azzera il limite; usa dry_run per verificare una nota prima di inviare. |
| 429 | too_many_active_notifications | Il negozio ha già 5 notifiche di aggiornamento prodotto in coda o in invio, attraverso tutti i prodotti e tutte le origini. error.details.limit è il limite e error.details.active_notification_ids elenca quelle campagne, dalla più vecchia. Non c'è alcun Retry-After: interroga GET /notifications/{id} per una di esse e riprova quando sarà terminata. Un dry run viene rifiutato allo stesso modo; in una scrittura di mappatura viene invece riportato in data.notification. |
| 500 | internal_error | Errore imprevisto del server. Su POST /products/{id}/notifications ogni 500 rilascia l'Idempotency-Key, quindi riprova la stessa richiesta con la stessa chiave. Lì sono previsti tre casi: Shopify non è riuscito a restituire i metacampi del prodotto per la nota, Shopify non è riuscito a confermare i variant_ids richiesti, oppure la creazione ha atteso più di 8 secondi dietro le altre creazioni del negozio. Se il tentativo fallito ha comunque messo in coda la campagna, il nuovo tentativo viene rifiutato con 429 notification_cooldown invece di avviarne una seconda. |
Documentazione API
È stato utile?
Ultimo aggiornamento 2026-10-20