Codici di stato HTTP per Azure Cosmos DB

  • Articolo

Questo articolo fornisce i codici di stato HTTP restituiti dalle operazioni REST.

Codice Descrizione
200 OK Una delle operazioni REST seguenti ha avuto esito positivo:

- GET in una risorsa.
- PUT in una risorsa.
- POST in una risorsa.
- POST in una risorsa di stored procedure per eseguire la stored procedure.
201 Creato Un'operazione POST per creare una risorsa ha esito positivo.
204 Nessun contenuto L'operazione DELETE è riuscita.
400 Richiesta non valida L'oggetto JSON, SQL o JavaScript nel corpo della richiesta non è valido.

Il codice 400 può essere restituito anche quando le proprietà necessarie di una risorsa non sono presenti o non sono state impostate nel corpo di POST o PUT sulla risorsa.

Il codice 400 viene restituito anche quando viene eseguito l'override del livello consistent per un'operazione GET con una coerenza più elevata da uno dei set per l'account.

400 viene restituito anche quando una richiesta che richiede una x-ms-documentdb-partitionkey non la include.
401 - Non autorizzato 401 viene restituito quando l'intestazione Authorization non è valida per la risorsa richiesta.
403 - Accesso negato Il token di autorizzazione è scaduto.

Il codice 403 viene restituito anche durante un'operazione per creare una POST risorsa al raggiungimento della quota di risorsa. Un esempio di questo scenario è quando si tenta di aggiungere documenti a una raccolta che ha raggiunto il provisioning dell'archiviazione.

L'errore 403 può essere restituito anche quando una stored procedure, un trigger o una funzione definita dall'utente sono stati contrassegnati per l'utilizzo elevato di risorse e la loro esecuzione è stata bloccata.

L'errore 403 - Accesso negato viene restituito quando le regole del firewall configurate nell'account Azure Cosmos DB bloccano la richiesta. Eventuali richieste che hanno origine da computer non compresi nell'elenco di elementi consentiti ricevono un errore 403.

403.3: questo codice di stato viene restituito per le richieste di scrittura durante l'operazione di failover manuale. Questo codice di stato viene usato come codice di reindirizzamento da parte dei driver per inoltrare le richieste di scrittura a una nuova area di scrittura. Il client REST diretto deve eseguire il comando GET in DatabaseAccount per identificare l'area di scrittura corrente e inoltrare la richiesta a tale endpoint.
404 - Non trovato L'operazione tenta di agire su una risorsa che non esiste più. Ad esempio, è possibile che la risorsa sia stata già eliminata.
408 - Timeout richiesta L'operazione non è stata completata entro l'intervallo di tempo assegnato. Questo codice viene restituito quando una stored procedure, un trigger o una funzione definita dall'utente (all'interno di una query) non completa l'esecuzione entro il tempo massimo di esecuzione.
409 - Conflitto L'ID specificato per una risorsa su un'operazione PUT o POST è stato usato da una risorsa esistente. Per risolvere il problema, usare un ID diverso per la risorsa. Per le raccolte partizionate, l'ID deve essere univoco in tutti i documenti con lo stesso valore della chiave di partizione.
412 Errore di precondizione L'operazione ha specificato un eTag diverso dalla versione disponibile nel server, ovvero un errore di concorrenza ottimistica. Riprovare a eseguire la richiesta dopo aver letto la versione più recente della risorsa e aver aggiornato l'ETag sulla richiesta.
413 - Entità troppo grande Le dimensioni del documento nella richiesta superano le dimensioni consentite per i documenti in una richiesta. Le dimensioni massime disponibili per il documento sono 2 MB.
423 - Bloccato Non è possibile eseguire l'operazione di ridimensionamento della velocità effettiva perché è in corso un'altra operazione di ridimensionamento.
424 - Dipendenza non riuscita Quando un'operazione di documento ha esito negativo nell'ambito transazionale di un'operazione TransactionalBatch, tutte le altre operazioni all'interno del batch vengono considerate dipendenze non riuscite. Questo codice di stato indica che l'operazione corrente è stata considerata non riuscita a causa di un altro errore all'interno dello stesso ambito transazionale.
429 Troppe richieste La raccolta ha superato il limite di velocità effettiva previsto. Ripetere la richiesta dopo che è trascorso il tempo specificato dal server per effettuare un nuovo tentativo. Per altre informazioni, vedere Unità richiesta.
449 Riprovare con L'operazione ha rilevato un errore temporaneo. Questo codice si verifica solo nelle operazioni di scrittura. È possibile riprovare l'operazione.
500 Errore interno del server L'operazione non è riuscita a causa di un errore imprevisto del servizio. Contattare il supporto tecnico. Vedere L'archiviazione di un problema di supporto tecnico di Azure.
503 - Servizio non disponibile Impossibile completare l'operazione perché il servizio non è stato disponibile. Questa situazione può verificarsi a causa di problemi di connettività di rete o disponibilità del servizio. È possibile riprovare l'operazione. Se il problema persiste, contattare il supporto tecnico.

Codici substatus HTTP

Quando si usano chiavi Customer-Managed (CMK) in Azure Cosmos DB, se si verificano errori, Azure Cosmos DB restituisce i dettagli dell'errore insieme a un codice substatus HTTP nella risposta. È possibile usare questo codice substatus per eseguire il debug della causa radice del problema. Attualmente Azure Cosmos DB supporta i seguenti codici substatus:

Codici substatus per i problemi lato server

I codici substatus seguenti sono supportati da Azure Cosmos DB per i problemi lato server:

Codice substatus Descrizione
4000 (Impossibile ottenere/accedere al token di Azure AD) Questo errore si verifica se Azure Cosmos DB non può ottenere il token di accesso di Azure Active Directory (Azure AD). Questo token è necessario per Azure Cosmos DB per accedere all'Key Vault. L'errore potrebbe verificarsi a causa di un problema di rete o di un problema del data center e non è qualcosa che l'utente può eseguire un'azione. Creare una richiesta di supporto per raggiungere il team di Azure Cosmos DB per risolvere il problema.
4001 (servizio Azure AD non è disponibile) Questo errore si verifica se il servizio Azure AD è inattivo o ha problemi. È possibile controllare il dashboard di interruzione di Azure per verificare se è presente un'interruzione esistente. Queste interruzioni vengono in genere risolte entro un paio di ore. È consigliabile contattare il team di Azure AD e informare il problema visualizzato. Se il team di Azure AD rileva che non esiste alcun problema, creare una richiesta di supporto per raggiungere il team di Azure Cosmos DB per la risoluzione.
4004 (servizio Key Vault non disponibile) Questo errore si verifica se Azure Cosmos DB tenta di accedere alla Key Vault, ma il servizio non è disponibile. Questo potrebbe essere dovuto a un problema di rete per raggiungere Key Vault o il servizio stesso potrebbe essere inattivo. È possibile controllare il dashboard di interruzione di Azure per verificare se è presente un'interruzione esistente. Queste interruzioni vengono in genere risolte entro un paio di ore. È consigliabile contattare il team Key Vault e informare il problema visualizzato. Se il team Key Vault rileva che non esiste alcun problema, creare una richiesta di supporto per raggiungere il team di Azure Cosmos DB per la risoluzione.
4007 (errore interno del server) Si tratta di un errore interno del server e si verifica se i byte di input non sono nel formato base64.
4008 (Key Vault errori del servizio interno) Questo errore si verifica se Azure Cosmos DB non è in grado di accedere al Key Vault. Potrebbe essere dovuto a un problema di rete o se il servizio Key Vault stesso è inattivo. È possibile controllare il dashboard di interruzione di Azure per verificare se è presente un'interruzione del servizio. Queste interruzioni vengono in genere risolte entro un paio di ore. È consigliabile contattare il team di Key Vault e segnalare il problema riscontrato. Se il team di Key Vault rileva che non esiste alcun problema, contattare il team di Azure Cosmos DB per la risoluzione.
1013 (operazione di creazione raccolta in corso) Se si verifica un'eccezione di timeout durante la creazione di una raccolta, eseguire un'operazione di lettura per verificare se la raccolta è stata creata correttamente. L'operazione di lettura genera un'eccezione finché l'operazione di creazione della raccolta non riesce. Se l'operazione di lettura genera un'eccezione con il codice di stato 404 e il codice di stato secondario 1013, significa che l'operazione di creazione della raccolta è ancora in corso. Ripetere l'operazione di lettura fino a quando non si ottengono codici di stato 200 o 201, questi codici informano che la raccolta è stata creata correttamente.

Codici di stato secondario per i problemi dell'utente finale

I codici di stato secondario seguenti sono supportati da Azure Cosmos DB per i problemi causati dall'utente finale:

Codice dello stato secondario Descrizione
4002 (Key Vault non concede l'autorizzazione ad Azure AD o la chiave è disabilitata) Questo problema si verifica se l'identità di Azure Cosmos DB è stata rimossa dai criteri di accesso Key Vault o se la chiave è stata disabilitata. Questo problema è in genere causato dall'utente finale. Se si verifica questo errore, assicurarsi che Azure Cosmos DB abbia accesso al Key Vault e che la chiave sia abilitata.
4003 (chiave non trovata) Questo problema si verifica se la chiave viene eliminata dal Key Vault. Questo problema è in genere causato dall'utente finale. Uno dei prerequisiti per l'uso di Azure Cosmos DB con chiavi gestite dal cliente è che il Key Vault ha la protezione dell'eliminazione temporanea e dell'eliminazione abilitata. Ciò significa che è possibile ripristinare la chiave eliminata e ripristinare l'accesso ad Azure Cosmos DB.
4005 (Impossibile eseguire il wrapping o annullare il wrapping della chiave) Questo errore si verifica se il Key Vault non è in grado di eseguire il wrapping o annullare il wrapping della chiave. Questo problema è in genere causato dall'utente finale. Una delle possibili cause di questo errore è che il Key Vault non è riuscito a decodificare il BLOB crittografato usando la chiave più recente perché la chiave è stata ruotata. Per risolvere questo errore, abilitare le chiavi disabilitate di recente e verrà risolto in circa un'ora. Se il problema non viene risolto dopo più di 2 ore, passare il problema ad Azure Cosmos DB.
4006 (URL chiave non valido) Questo errore si verifica durante il provisioning se è stata inclusa la versione della chiave nell'URL Key Vault. Questo errore è spesso causato dall'utente finale. Per risolvere questo errore, rimuovere la versione e riprovare. Ad esempio, se è stato usato l'URL nel formato https://<KeyVaultName>.vault.azure.net/keys/<KeyName>/<KeyVersion>, aggiornarlo a https://<KeyVaultName>.vault.azure.net/keys/<KeyName>/
4009 (non è possibile risolvere Key Vault nome DNS) Questo errore si verifica se non è stato possibile risolvere il nome DNS Key Vault perché è stato usato il nome Key Vault non corretto. Questo errore è causato dall'utente finale. Per risolverlo, correggere il nome Key Vault e riprovare.

Vedere anche