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 transactional: 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.