Erros e processamento de erros

Quando um pedido do Firestore no modo Datastore é bem-sucedido, a API devolve um código de estado HTTP 200 OK juntamente com os dados pedidos no corpo da resposta.

Quando um pedido falha, a API Datastore devolve um código de estado HTTP 4xx ou 5xx que identifica genericamente a falha, bem como uma resposta que fornece informações mais específicas sobre os erros que causaram a falha.

O resto desta página descreve a estrutura de um erro, enumera códigos de erros específicos e recomenda como resolvê-los.

Segue-se a estrutura de uma resposta de erro para um pedido JSON:

{
  "error": {
    "code": "integer",
    "message": "string",
    "status": "string"
  }
}

O objeto de resposta contém um único campo error cujo valor contém os seguintes elementos:

Elemento Descrição
code Um código de estado HTTP que identifica genericamente a falha do pedido.
message Informações específicas sobre a falha do pedido.
status O código de erro canónico (google.rpc.Code) para as APIs Google. Os códigos que podem ser devolvidos pela API Datastore estão listados em Códigos de erro.

Segue-se um exemplo de uma resposta de erro para um pedido JSON:

{
  "error": {
    "code": 400,
    "message": "Key path is incomplete: [Person: null]",
    "status": "INVALID_ARGUMENT"
  }
}

Se uma solicitação feita com um tipo de conteúdo de application/x-protobuf resultar num erro, devolve uma mensagem google.rpc.Status serializada como a carga útil.

Códigos de erro

A forma recomendada de classificar os erros é inspecionar o valor do código de erro canónico (google.rpc.Code). Nos erros JSON, este código aparece no campo status. Nos erros application/x-protobuf, está no campo code.

Código de erro canónico Descrição Ação recomendada
ABORTED Indica que o pedido entrou em conflito com outro pedido. Para uma confirmação não transacional:
tente novamente o pedido ou estruture as suas entidades para reduzir a contenção.

Para pedidos que fazem parte de uma confirmação transacional:
tente novamente toda a transação ou estruture as suas entidades para reduzir a contenção.
ALREADY_EXISTS Indica que o pedido tentou inserir uma entidade que já existe. Não tente novamente sem corrigir o problema.
DEADLINE_EXCEEDED Foi excedido um prazo no servidor. Tente novamente com retirada exponencial.
FAILED_PRECONDITION Indica que não foi cumprida uma pré-condição para o pedido. O campo de mensagem na resposta de erro fornece informações sobre a pré-condição que falhou. Uma possível causa é a execução de uma consulta que requer um índice ainda não definido. Não tente novamente sem corrigir o problema.
INTERNAL O servidor devolveu um erro. Não tente repetir este pedido mais do que uma vez.
INVALID_ARGUMENT Indica que um parâmetro de pedido tem um valor inválido. O campo de mensagem na resposta de erro fornece informações sobre o valor que era inválido. Não tente novamente sem corrigir o problema.
NOT_FOUND Indica que o pedido tentou atualizar uma entidade que não existe. Não tente novamente sem corrigir o problema.
PERMISSION_DENIED Indica que o utilizador não tinha autorização para fazer o pedido. Não tente novamente sem corrigir o problema.
RESOURCE_EXHAUSTED Indica que o projeto excedeu a respetiva quota ou a capacidade da região/multirregião. Confirme que não excedeu a quota do seu projeto. Se excedeu uma quota de projeto, não tente novamente sem corrigir o problema.

Caso contrário, tente novamente com um recuo exponencial.
UNAUTHENTICATED Indica que o pedido não tinha credenciais de autenticação válidas. Não tente novamente sem corrigir o problema.
UNAVAILABLE O servidor devolveu um erro. Tente novamente com retirada exponencial.