Errori | Documentazione - Roblox Hub Creatori

Le sezioni seguenti descrivono la gestione degli errori per le API di Open Cloud. A causa delle differenze di implementazione tra gli endpoint e i livelli di validazione, le risposte di errore possono variare significativamente nel formato.

Errori di gateway

Per problemi di autenticazione o routing, sia le API Open Cloud v1 che v2 possono restituire errori in questo formato:

Esempio di errore di gateway
{
  "errors": [
    {
      "code": 0,
      "message": "Chiave API non valida"
    }
  ]
}

Open Cloud v2

Le API Open Cloud v2 seguono generalmente un formato di errore coerente quando l'errore si verifica all'interno del endpoint API stesso.

Formato di errore standard v2

Le API Open Cloud v2 restituiscono errori in questo formato:

code - Una stringa che rappresenta il tipo di errore (ad es. INVALID_ARGUMENT, NOT_FOUND).
message - Un messaggio leggibile dall'utente che spiega l'errore.
details - Un array opzionale contenente ulteriori informazioni specifiche sull'errore.

Esempio di errore v2
{
  "code": "INVALID_ARGUMENT",
  "message": "ID utente non valido nella richiesta."
}

Esempio di errore v2 con dettagli
{
  "code": "INVALID_ARGUMENT",
  "message": "Il filtro fornito non è valido.",
  "details": [
    {
      ...
    }
  ]
}

Codici di errore v2

La seguente tabella descrive i possibili valori per code nelle risposte API v2.

Codice	Status HTTP	Descrizione
INVALID_ARGUMENT	400	Hai passato un argomento non valido, come un universeId non valido. Potresti anche avere intestazioni mancanti o non valide, come Content-Length e Content-Type.
PERMISSION_DENIED	403	La tua richiesta non ha autorizzazioni o ambiti sufficienti per eseguire l'operazione.
NOT_FOUND	404	Il sistema non riesce a trovare le risorse specificate, come una voce nel data store.
ABORTED	409	L'operazione è stata annullata.
RESOURCE_EXHAUSTED	429	Non hai abbastanza quota per eseguire l'operazione, tipicamente a causa dell'invio di troppe richieste.
CANCELLED	499	Il sistema termina la richiesta, tipicamente a causa di un timeout lato client.
INTERNAL	500	Errore interno del server, tipicamente a causa di un bug del server.
NOT_IMPLEMENTED	501	Il server non implementa il metodo API.
UNAVAILABLE	503	Servizio non disponibile, tipicamente restituito quando il server è inattivo.

Open Cloud v1

Le API Open Cloud v1 presentano formati di risposta di errore inconsistenti. Il formato dipende dall'endpoint specifico, dal tipo di errore e da dove si verifica l'errore nella pipeline di elaborazione della richiesta.

La maggior parte degli endpoint v1 restituisce errori in uno di questi tre formati:

Esempio di errore v1 con campo error
{
  "error": "INVALID_ARGUMENT",
  "message": "Cursore non valido.",
  "errorDetails": [
    {
      "errorDetailType": "DatastoreErrorInfo",
      "datastoreErrorCode": "InvalidCursor"
    }
  ]
}

Esempio di errore v1 con campo code
{
  "code": "INVALID_ARGUMENT",
  "message": "Cursore non valido."
}

Esempio di errore di validazione dettagliato v1
{
  "errors": {
    "assetId": ["Il valore 'a' non è valido."]
  },
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Si sono verificati uno o più errori di validazione.",
  "status": 400,
  "extensions": {
    "traceId": "00-427917f0fc3b8375ee33e4603a7f0693-f3f6ad560ff1a122-00"
  }
}

Codici di errore v1

La seguente tabella descrive i possibili valori per error o code nelle risposte API v1:

Codice di Stato HTTP	Errore	Descrizioni
400	INVALID_ARGUMENT	Hai passato un argomento non valido, come un universeId non valido. Potresti anche avere intestazioni mancanti o non valide, come Content-Length e Content-Type.
403	INSUFFICIENT_SCOPE	La richiesta richiede privilegi superiori a quelli forniti dal token di accesso.
403	PERMISSION_DENIED	La tua richiesta non ha ambiti sufficienti per eseguire l'operazione.
404	NOT_FOUND	Il sistema non riesce a trovare le risorse specificate, come un data store.
409	ABORTED	L'operazione è stata annullata a causa di un conflitto, come pubblicare un luogo che non fa parte dell'universo.
429	RESOURCE_EXHAUSTED	Non hai abbastanza quota per eseguire l'operazione, tipicamente a causa dell'invio di troppe richieste.
499	CANCELLED	Il sistema termina la richiesta, tipicamente a causa di un timeout lato client.
500	INTERNAL	Errore interno del server. Tipicamente un bug del server.
501	NOT_IMPLEMENTED	Il server non implementa il metodo API.
503	UNAVAILABLE	Servizio non disponibile. Tipicamente il server è inattivo.