Fehler | Dokumentation - Roblox Creator Hub

Die folgenden Abschnitte beschreiben das Fehlerhandling der Open Cloud-APIs. Aufgrund von Implementierungsunterschieden zwischen Endpunkten und Validierungsschichten können Fehlerantworten erheblich im Format variieren.

Gateway-Fehler

Bei Authentifizierungs- oder Routingproblemen können sowohl die Open Cloud v1 als auch die v2 APIs Fehler in diesem Format zurückgeben:

Beispiel für einen Gateway-Fehler
{
  "errors": [
    {
      "code": 0,
      "message": "Ungültiger API-Schlüssel"
    }
  ]
}

Open Cloud v2

Die Open Cloud v2 APIs folgen im Allgemeinen einem konsistenten Fehlerformat, wenn der Fehler innerhalb des API-Endpunkts selbst auftritt.

Standard v2 Fehlerformat

Die Open Cloud v2 APIs geben Fehler in diesem Format zurück:

code - Ein String, der den Fehler Typ repräsentiert (z. B. INVALID_ARGUMENT, NOT_FOUND).
message - Eine menschenlesbare Nachricht, die den Fehler erklärt.
details - Ein optionales Array, das zusätzliche fehler spezifische Informationen enthält.

Beispiel für einen v2 Fehler
{
  "code": "INVALID_ARGUMENT",
  "message": "Ungültige Benutzer-ID in der Anfrage."
}

Beispiel für einen v2 Fehler mit Details
{
  "code": "INVALID_ARGUMENT",
  "message": "Der angegebene Filter ist ungültig.",
  "details": [
    {
      ...
    }
  ]
}

v2 Fehlercodes

Die folgende Tabelle beschreibt mögliche Werte für code in den v2 API-Antworten.

Code	HTTP-Status	Beschreibung
INVALID_ARGUMENT	400	Sie haben ein ungültiges Argument übergeben, wie eine ungültige universeId. Möglicherweise fehlen auch Header oder sind ungültig, wie Content-Length und Content-Type.
PERMISSION_DENIED	403	Ihre Anfrage hat nicht genügend Berechtigungen oder Scopes, um die Operation auszuführen.
NOT_FOUND	404	Das System kann Ihre angegebenen Ressourcen nicht finden, z. B. einen Datenspeichereintrag.
ABORTED	409	Die Operation wurde abgebrochen.
RESOURCE_EXHAUSTED	429	Sie haben nicht genügend Kontingent, um die Operation auszuführen, typischerweise aufgrund von zu vielen gesendeten Anfragen.
CANCELLED	499	Das System beendet die Anfrage, in der Regel aufgrund eines Timeouts auf der Client-Seite.
INTERNAL	500	Interner Serverfehler, typischerweise aufgrund eines Serverfehlers.
NOT_IMPLEMENTED	501	Der Server implementiert die API-Methode nicht.
UNAVAILABLE	503	Der Dienst ist nicht verfügbar, typischerweise angezeigt, wenn der Server nicht verfügbar ist.

Open Cloud v1

Die Open Cloud v1 APIs haben inkonsistente Fehlerantworthierformate. Das Format hängt vom spezifischen Endpunkt, der Art des Fehlers und davon ab, wo der Fehler im Anfrageverarbeitungsprozess auftritt.

Die meisten v1-Endpunkte geben Fehler in einem dieser drei Formate zurück:

Beispiel für einen v1 Fehler mit Fehlerfeld
{
  "error": "INVALID_ARGUMENT",
  "message": "Ungültiger Cursor.",
  "errorDetails": [
    {
      "errorDetailType": "DatastoreErrorInfo",
      "datastoreErrorCode": "InvalidCursor"
    }
  ]
}

Beispiel für einen v1 Fehler mit Codefeld
{
  "code": "INVALID_ARGUMENT",
  "message": "Ungültiger Cursor."
}

Beispiel für einen v1 detaillierten Validierungsfehler
{
  "errors": {
    "assetId": ["Der Wert 'a' ist nicht gültig."]
  },
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Es sind ein oder mehrere Validierungsfehler aufgetreten.",
  "status": 400,
  "extensions": {
    "traceId": "00-427917f0fc3b8375ee33e4603a7f0693-f3f6ad560ff1a122-00"
  }
}

v1 Fehlercodes

Die folgende Tabelle beschreibt mögliche Werte für error oder code in v1 API-Antworten:

HTTP-Statuscode	Fehler	Beschreibungen
400	INVALID_ARGUMENT	Sie haben ein ungültiges Argument übergeben, wie eine ungültige universeId. Möglicherweise fehlen auch Header oder sind ungültig, wie Content-Length und Content-Type.
403	INSUFFICIENT_SCOPE	Die Anfrage erfordert höhere Berechtigungen als die, die durch das Zugriffstoken bereitgestellt werden.
403	PERMISSION_DENIED	Ihre Anfrage hat nicht genügend Scope, um die Operation auszuführen.
404	NOT_FOUND	Das System kann Ihre angegebenen Ressourcen nicht finden, z. B. einen Datenspeicher.
409	ABORTED	Die Operation wurde aufgrund eines Konflikts abgebrochen, z. B. durch das Veröffentlichen eines Ortes, der nicht Teil des Universums ist.
429	RESOURCE_EXHAUSTED	Sie haben nicht genügend Kontingent, um die Operation auszuführen, typischerweise aufgrund von zu vielen gesendeten Anfragen.
499	CANCELLED	Das System beendet die Anfrage, typischerweise aufgrund eines Timeouts auf der Client-Seite.
500	INTERNAL	Interner Serverfehler. Typischerweise ein Serverfehler.
501	NOT_IMPLEMENTED	Der Server implementiert die API-Methode nicht.
503	UNAVAILABLE	Dienst nicht verfügbar. Typischerweise ist der Server nicht verfügbar.