Codici di errore

Se una richiesta non riesce, controlla il codice di errore nella risposta. Aprilo nell’elenco per sapere cosa è successo e come procedere. Ogni errore include anche un esempio di risposta e indicazioni su quando riprovare.

400request.malformedNon è possibile interpretare la richiesta.

Cosa fare: Verifica sintassi JSON, codifica URL e struttura della richiesta.
Regola di ripetizione: Riprova dopo aver corretto la richiesta.

Risposta

{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsLa chiave API o il token non sono validi, sono scaduti o sono stati revocati.

Cosa fare: Verifica URL del negozio e credenziali. Ottieni un nuovo token con una chiave API attiva.
Regola di ripetizione: Riprova dopo aver corretto l’autenticazione; evita richieste ripetute con token non validi.

Risposta

{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.requiredL’header Authorization obbligatorio è assente o usa uno schema errato.

Cosa fare: Per emettere o revocare un token, usa la chiave API con ApiKey nell’intestazione Authorization. Per le altre richieste, usa il token di accesso con Bearer.
Regola di ripetizione: Riprova dopo aver fornito l’header corretto.

Risposta

{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverifiedIl servizio non ha potuto verificare in modo affidabile l’indirizzo IP del client.

Cosa fare: Controlla da quale indirizzo IP l’integrazione si collega all’API. Se l’errore persiste, contatta l’assistenza tecnica Shopently.
Regola di ripetizione: Riprova dopo aver risolto il problema di identificazione dell’indirizzo IP.

Risposta

{
  "error": {
    "code": "authorization.client_ip_unverified",
    "fields": null,
    "message": "The client IP address could not be verified."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.ip_not_allowedL’indirizzo IP di origine non è nell’elenco consentito per la chiave.

Cosa fare: Usa un indirizzo approvato oppure chiedi a un amministratore autorizzato di modificare l’elenco IP della chiave.
Regola di ripetizione: Riprova soltanto dopo l’autorizzazione dell’indirizzo.

Risposta

{
  "error": {
    "code": "authorization.ip_not_allowed",
    "fields": null,
    "message": "Access from this IP address is not allowed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.scope_deniedLa chiave non ha un permesso effettivo necessario per questa operazione.

Cosa fare: Verifica permessi obbligatori e condizionali dell’operazione, concessioni della chiave e diritti dell’emittente.
Regola di ripetizione: Riprova dopo che un amministratore autorizzato ha concesso l’accesso necessario.

Risposta

{
  "error": {
    "code": "authorization.scope_denied",
    "fields": null,
    "message": "The required permission has not been granted."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.api_disabledL’accesso API è disabilitato per questo negozio.

Cosa fare: Chiedi al proprietario di verificare il piano attivo e la disponibilità dell’API.
Regola di ripetizione: Non riprovare finché l’accesso API non viene abilitato.

Risposta

{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceededLa modifica supererebbe un limite del piano corrente.

Cosa fare: Verifica il limite applicabile e modifica l’operazione prevista o il piano.
Regola di ripetizione: Riprova dopo aver risolto il limite; usa una nuova chiave di idempotenza se cambia la richiesta.

Risposta

{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabledIl piano corrente non comprende questa operazione.

Cosa fare: Verifica il piano minimo indicato per l’operazione.
Regola di ripetizione: Riprova quando il piano consente l’operazione e la chiave ha i permessi necessari.

Risposta

{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blockedUn limite del piano blocca questa risorsa specifica.

Cosa fare: Chiedi al proprietario di risolvere la restrizione del piano sulla risorsa.
Regola di ripetizione: Non ripetere la stessa richiesta mentre la risorsa resta bloccata.

Risposta

{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_foundLa risorsa è assente, eliminata o non disponibile con l’identificativo indicato.

Cosa fare: Verifica negozio, percorso e identificativo. Usa gli identificativi restituiti da questo negozio.
Regola di ripetizione: Riprova soltanto dopo aver corretto la destinazione o confermato che esista.

Risposta

{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowedL’endpoint non supporta questo metodo HTTP.

Cosa fare: Usa il metodo documentato; l’header Allow indica quelli supportati.
Regola di ripetizione: Non ripetere il metodo non supportato.

Risposta

{
  "error": {
    "code": "request.method_not_allowed",
    "fields": null,
    "message": "This method is not supported for this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409idempotency.key_reusedLa chiave di idempotenza appartiene a una richiesta diversa.

Cosa fare: Individua l’operazione originale. Usa una nuova chiave soltanto per una nuova operazione logica intenzionale.
Regola di ripetizione: Non ripetere un contenuto modificato con la chiave in conflitto.

Risposta

{
  "error": {
    "code": "idempotency.key_reused",
    "fields": null,
    "message": "This idempotency key was used with a different request."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.already_existsUn valore univoco è in conflitto con una risorsa esistente.

Cosa fare: Leggi la risorsa esistente e decidi se usarla o scegliere un altro valore univoco.
Regola di ripetizione: Non ripetere la stessa creazione in conflitto.

Risposta

{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_useAltre risorse dipendono ancora da questa risorsa.

Cosa fare: Esamina le dipendenze e rimuovile o modificale mediante operazioni supportate prima dell’eliminazione.
Regola di ripetizione: Riprova dopo aver risolto le dipendenze.

Risposta

{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflictLo stato operativo corrente impedisce questa modifica.

Cosa fare: Leggi lo stato corrente e scegli una transizione valida.
Regola di ripetizione: Non forzare automaticamente la modifica in conflitto e non inviarla ripetutamente.

Risposta

{
  "error": {
    "code": "resource.state_conflict",
    "fields": null,
    "message": "The current resource state does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.version_conflictUn’altra scrittura ha modificato la risorsa dopo la versione che hai letto.

Cosa fare: Leggi lo stato più recente, riconcilia la modifica e invia la nuova expected_version.
Regola di ripetizione: Usa una nuova chiave di idempotenza per l’operazione rivista; non sovrascrivere alla cieca.

Risposta

{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409storage.limit_reachedÈ stato raggiunto il limite di spazio per immagini e file. Libera spazio o aumenta il limite.

Cosa fare: È stato raggiunto il limite di spazio per immagini e file. Libera spazio o aumenta il limite.
Regola di ripetizione: Riprova con operazioni valide più piccole, ognuna con la propria chiave di idempotenza.

Risposta

{
  "error": {
    "code": "storage.limit_reached",
    "fields": null,
    "message": "The upload storage limit is reached."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_largeLa richiesta supera il limite di dimensione.

Cosa fare: Riduci il contenuto o suddividi il lavoro in singole operazioni supportate.
Regola di ripetizione: Riprova con operazioni valide più piccole, ognuna con la propria chiave di idempotenza.

Risposta

{
  "error": {
    "code": "request.too_large",
    "fields": null,
    "message": "The request exceeds the size limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

415request.unsupported_media_typeIl tipo di contenuto o la sua codifica non sono supportati.

Cosa fare: Per scritture JSON usa Content-Type: application/json e un corpo non compresso supportato.
Regola di ripetizione: Riprova dopo aver corretto il tipo di contenuto o la codifica.

Risposta

{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

416request.range_not_satisfiableVincoli: Range

Cosa fare: Range: bytes=0-(size_bytes-1)
Regola di ripetizione: Riprova dopo aver corretto la richiesta.

Risposta

{
  "error": {
    "code": "request.range_not_satisfiable",
    "fields": null,
    "message": "The requested byte range is unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failedUno o più campi o parametri non superano la validazione.

Cosa fare: Esamina error.fields, poi verifica campi obbligatori, ammissibilità di null, identificativi e valori consentiti.
Regola di ripetizione: Riprova con una richiesta corretta; una scrittura modificata costituisce una nuova operazione logica.

Risposta

{
  "error": {
    "code": "request.validation_failed",
    "fields": null,
    "message": "Some request parameters are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.queue_fullLa breve coda dell’API è piena; l’esecuzione della richiesta non è iniziata.

Cosa fare: Accoda le richieste e rispetta l’header Retry-After della risposta.
Regola di ripetizione: Attendi almeno i secondi indicati in Retry-After. Se ripeti una scrittura, mantieni lo stesso corpo della richiesta e lo stesso valore di Idempotency-Key.

Risposta

{
  "error": {
    "code": "capacity.queue_full",
    "fields": null,
    "message": "The API is busy. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.wait_timeoutIl tempo di attesa nella coda dell’API è scaduto; l’esecuzione della richiesta non è iniziata.

Cosa fare: Accoda le richieste e rispetta l’header Retry-After della risposta.
Regola di ripetizione: Attendi almeno i secondi indicati in Retry-After. Se ripeti una scrittura, mantieni lo stesso corpo della richiesta e lo stesso valore di Idempotency-Key.

Risposta

{
  "error": {
    "code": "capacity.wait_timeout",
    "fields": null,
    "message": "The API could not start this request in time. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429rate_limit.exceededLa frequenza delle richieste supera il limite applicabile.

Cosa fare: Accoda le richieste e rispetta l’header Retry-After della risposta.
Regola di ripetizione: Attendi almeno i secondi indicati in Retry-After. Se ripeti una scrittura, mantieni lo stesso corpo della richiesta e lo stesso valore di Idempotency-Key.

Risposta

{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.errorSi è verificato un errore imprevisto del servizio.

Cosa fare: Attendi un momento prima di ripetere la richiesta. Se l’errore 500 si ripresenta, contatta l’assistenza tecnica Shopently e indica l’identificativo della richiesta.
Regola di ripetizione: Puoi riprovare a leggere i dati dopo una breve pausa. Per ripetere una scrittura, usa lo stesso valore di Idempotency-Key e lascia invariato il corpo della richiesta.

Risposta

{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_responseIl gateway non ha ricevuto una risposta API valida.

Cosa fare: Conserva l’identificativo della richiesta. Una risposta fallita non dimostra che una scrittura non sia stata applicata.
Regola di ripetizione: Usa attese crescenti con un numero limitato di tentativi; ripeti la stessa scrittura logica con Idempotency-Key e contenuto originali.

Risposta

{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableL’API non può gestire temporaneamente la richiesta.

Cosa fare: Se la risposta contiene l’intestazione Retry-After, attendi il numero di secondi indicato prima di riprovare. Altrimenti attendi un momento. Se l’errore persiste, contatta l’assistenza tecnica Shopently e indica l’identificativo della richiesta.
Regola di ripetizione: Riprova dopo aver atteso come indicato sopra. Per ripetere una scrittura, usa lo stesso valore di Idempotency-Key e lascia invariato il corpo della richiesta.

Risposta

{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeoutIl gateway ha superato il tempo di attesa dell’API.

Cosa fare: Se la richiesta modificava dei dati, controlla se le modifiche sono state salvate nel negozio. L’assenza di una risposta non significa che il salvataggio non sia riuscito. Se l’errore persiste, contatta l’assistenza tecnica Shopently e indica l’identificativo della richiesta.
Regola di ripetizione: Puoi riprovare a leggere i dati dopo una breve pausa. Per ripetere una scrittura, usa lo stesso valore di Idempotency-Key e lascia invariato il corpo della richiesta.

Risposta

{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}