Errori e recupero

Usa i codici stabili per decidere se correggere, attendere o riprovare.

Cosa fare

Basa la logica sullo stato HTTP e su error.code, non sul testo di error.message.
Un 401 richiede un’autenticazione valida; un 403 una verifica di accessi o piano; un 409 una verifica dell’operazione in conflitto o della versione della risorsa.

Accesso negato e nuovi tentativi

401: 401 non significa sempre che il token sia scaduto. Se è scaduto, ottienine uno nuovo e ripeti la lettura al massimo una volta. Se la richiesta del token restituisce 401, verifica la chiave e interrompi i tentativi automatici.
403: In caso di 403, verifica i permessi, le restrizioni IP e il piano. Un nuovo token non ripristina un accesso revocato.

Autenticazione

Regola di ripetizione

Per i guasti temporanei usa un numero limitato di tentativi, con attese crescenti e una componente casuale.
Rispetta Retry-After quando presente.
Se una scrittura va in timeout, il suo esito può essere sconosciuto: ripeti la stessa operazione con Idempotency-Key e richiesta invariati.
Il catalogo seguente spiega tutti i codici pubblicati.

Scritture sicure

Limiti di frequenza

422 / 409

Per i prezzi, un formato della valuta o una precisione dell’importo non validi restituiscono 422 request.validation_failed.
Un codice valuta valido ma diverso da quello del listino selezionato restituisce 409 resource.version_conflict.
Controlla il contesto e le versioni prima di riprovare.

Catalogo degli errori

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.

JSON

{
  "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.

JSON

{
  "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: Usa ApiKey per richiedere un token e Bearer per le operazioni sulle risorse.
Regola di ripetizione: Riprova dopo aver fornito l’header corretto.

JSON

{
  "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: Chiedi all’operatore del negozio di verificare il percorso di ingresso. Non inserire autonomamente header di inoltro.
Regola di ripetizione: Riprova dopo il ripristino del percorso di connessione attendibile.

JSON

{
  "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.

JSON

{
  "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.

JSON

{
  "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.

JSON

{
  "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.

JSON

{
  "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.

JSON

{
  "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.

JSON

{
  "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.

JSON

{
  "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.

JSON

{
  "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.

JSON

{
  "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.

JSON

{
  "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.

JSON

{
  "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.

JSON

{
  "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.

JSON

{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "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.

JSON

{
  "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.

JSON

{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "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.

JSON

{
  "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 da Retry-After e aggiungi un ritardo casuale. Per ripetere una scrittura conserva chiave e contenuto originali.

JSON

{
  "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 da Retry-After e aggiungi un ritardo casuale. Per ripetere una scrittura conserva chiave e contenuto originali.

JSON

{
  "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 da Retry-After e aggiungi un ritardo casuale. Per ripetere una scrittura conserva chiave e contenuto originali.

JSON

{
  "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: Registra l’identificativo della richiesta e contatta l’operatore se l’errore persiste; escludi le credenziali dai log.
Regola di ripetizione: Usa tentativi limitati con attese crescenti. Per una scrittura mantieni chiave di idempotenza e contenuto originali.

JSON

{
  "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.

JSON

{
  "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: Rispetta Retry-After quando presente e conserva l’identificativo della richiesta se l’interruzione persiste.
Regola di ripetizione: Usa tentativi limitati con attese crescenti e un ritardo casuale; conserva chiave e contenuto per ripetere la stessa scrittura.

JSON

{
  "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: Conserva l’identificativo della richiesta e considera sconosciuto l’esito della scrittura.
Regola di ripetizione: Usa un numero limitato di tentativi con attese crescenti; per una scrittura mantieni chiave di idempotenza e contenuto originali.

JSON

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