Erros e tratamento de erros

Quando uma solicitação do Firestore no modo Datastore for bem-sucedida, a API retornará um código de status HTTP 200 OK junto com os dados solicitados no corpo da resposta.

Quando uma solicitação falha, a API Datastore retorna um código de status HTTP 4xx ou 5xx, que identifica a falha de maneira genérica, bem como uma resposta que fornece informações mais específicas sobre o erro que causou a falha.

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

Veja, a seguir, a estrutura de uma resposta de erro para uma solicitação JSON:

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

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

Elemento Descrição
code Um código de status HTTP que identifica a falha na solicitação de forma genérica.
message Informações específicas sobre a falha da solicitação.
status O código de erro canônico (google.rpc.Code) de APIs do Google. Os códigos que podem ser retornados pela API Datastore são listados em Códigos de erro.

Veja um exemplo de resposta de erro para uma solicitação JSON:

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

Se uma solicitação feita com o tipo de conteúdo application/x-protobuf gerar erro, ela retornará uma mensagem google.rpc.Status serializada como payload.

Códigos de erro

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

Código de erro canônico Descrição Ação recomendada
ABORTED Indica que a solicitação entrou em conflito com outra solicitação. Para uma confirmação não transacional:
repita a solicitação ou estruture suas entidades para reduzir a contenção.

Para solicitações que fazem parte de uma confirmação transacional:
repita toda a transação ou estruture suas entidades para reduzir a contenção.
ALREADY_EXISTS Indica que a solicitação tentou inserir uma entidade que já existe. Não tente novamente sem resolver o problema.
DEADLINE_EXCEEDED Um prazo excedeu no servidor. Tente novamente usando espera exponencial.
FAILED_PRECONDITION Indica que uma condição prévia para a solicitação não foi atendida. O campo de mensagem na resposta de erro fornece informações sobre essa condição. Uma possível causa é a execução de uma consulta que requer um índice ainda não definido. Não tente novamente sem resolver o problema.
INTERNAL O servidor retornou um erro. Não tente executar essa solicitação mais de uma vez.
INVALID_ARGUMENT Indica que um parâmetro de solicitação tem um valor inválido. O campo de mensagem na resposta de erro fornece informações sobre o valor inválido. Não tente novamente sem resolver o problema.
NOT_FOUND Indica que a solicitação tentou atualizar uma entidade que não existe. Não tente novamente sem resolver o problema.
PERMISSION_DENIED Indica que o usuário não foi autorizado a fazer a solicitação. Não tente novamente sem resolver o problema.
RESOURCE_EXHAUSTED Indica que o projeto excedeu sua cota ou a capacidade da região/multirregião. Verifique se você não ultrapassou a cota do projeto. Se você excedeu a cota do projeto, não repita sem corrigir o problema.

Caso contrário, tente novamente com espera exponencial.
UNAUTHENTICATED Indica que a solicitação não tinha credenciais de autenticação válidas. Não tente novamente sem resolver o problema.
UNAVAILABLE O servidor retornou um erro. Tente novamente usando espera exponencial.