Erros | Documentação - Central de Criadores Roblox

As seções a seguir descrevem o tratamento de erros para as APIs do Open Cloud. Devido a diferenças de implementação entre endpoints e camadas de validação, as respostas de erro podem variar significativamente em formato.

Erros de Gateway

Para problemas de autenticação ou roteamento, tanto as APIs Open Cloud v1 quanto v2 podem retornar erros neste formato:

Exemplo de erro de gateway
{
  "errors": [
    {
      "code": 0,
      "message": "Chave de API inválida"
    }
  ]
}

Open Cloud v2

As APIs Open Cloud v2 geralmente seguem um formato de erro consistente quando o erro ocorre dentro do próprio endpoint da API.

Formato padrão de erro v2

As APIs Open Cloud v2 retornam erros neste formato:

code - Uma string representando o tipo de erro (ex: INVALID_ARGUMENT, NOT_FOUND).
message - Uma mensagem legível que explica o erro.
details - Um array opcional contendo informações adicionais específicas do erro.

Exemplo de erro v2
{
  "code": "INVALID_ARGUMENT",
  "message": "ID de usuário inválido na requisição."
}

Exemplo de erro v2 com detalhes
{
  "code": "INVALID_ARGUMENT",
  "message": "O filtro fornecido é inválido.",
  "details": [
    {
      ...
    }
  ]
}

Códigos de erro v2

A tabela a seguir descreve os possíveis valores para code nas respostas da API v2.

Código	Status HTTP	Descrição
INVALID_ARGUMENT	400	Você passou um argumento inválido, como um universeId inválido. Você também pode ter cabeçalhos faltando ou inválidos, como Content-Length e Content-Type.
PERMISSION_DENIED	403	Sua requisição não tem permissões ou escopos suficientes para realizar a operação.
NOT_FOUND	404	O sistema não consegue encontrar os recursos que você especificou, como uma entrada no armazenamento de dados.
ABORTED	409	A operação foi abortada.
RESOURCE_EXHAUSTED	429	Você não tem cota suficiente para realizar a operação, geralmente devido ao envio de muitas requisições.
CANCELLED	499	O sistema encerra a requisição, geralmente devido a um tempo limite do lado do cliente.
INTERNAL	500	Erro interno do servidor, geralmente devido a um bug no servidor.
NOT_IMPLEMENTED	501	O servidor não implementa o método da API.
UNAVAILABLE	503	Serviço indisponível, normalmente retornado quando o servidor está fora do ar.

Open Cloud v1

As APIs Open Cloud v1 têm formatos de resposta de erro inconsistentes. O formato depende do endpoint específico, do tipo de erro e de onde o erro ocorre no pipeline de processamento da requisição.

A maioria dos endpoints v1 retorna erros em um destes três formatos:

Exemplo de erro v1 com campo de erro
{
  "error": "INVALID_ARGUMENT",
  "message": "Cursor inválido.",
  "errorDetails": [
    {
      "errorDetailType": "DatastoreErrorInfo",
      "datastoreErrorCode": "InvalidCursor"
    }
  ]
}

Exemplo de erro v1 com campo de código
{
  "code": "INVALID_ARGUMENT",
  "message": "Cursor inválido."
}

Exemplo de erro de validação detalhada v1
{
  "errors": {
    "assetId": ["O valor 'a' não é válido."]
  },
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Um ou mais erros de validação ocorreram.",
  "status": 400,
  "extensions": {
    "traceId": "00-427917f0fc3b8375ee33e4603a7f0693-f3f6ad560ff1a122-00"
  }
}

Códigos de erro v1

A tabela a seguir descreve os possíveis valores para error ou code nas respostas da API v1:

Código de Status HTTP	Erro	Descrições
400	INVALID_ARGUMENT	Você passou um argumento inválido, como um universeId inválido. Você também pode ter cabeçalhos faltando ou inválidos, como Content-Length e Content-Type.
403	INSUFFICIENT_SCOPE	A requisição requer privilégios mais altos do que os fornecidos pelo token de acesso.
403	PERMISSION_DENIED	Sua requisição não tem escopo suficiente para realizar a operação.
404	NOT_FOUND	O sistema não consegue encontrar os recursos que você especificou, como um armazenamento de dados.
409	ABORTED	A operação foi abortada devido a um conflito, como publicar um lugar que não faz parte do universo.
429	RESOURCE_EXHAUSTED	Você não tem cota suficiente para realizar a operação, normalmente devido ao envio de muitas requisições.
499	CANCELLED	O sistema encerra a requisição, tipicamente devido a um tempo limite do lado do cliente.
500	INTERNAL	Erro interno do servidor. Normalmente um bug do servidor.
501	NOT_IMPLEMENTED	O servidor não implementa o método da API.
503	UNAVAILABLE	Serviço indisponível. Normalmente o servidor está fora do ar.