Ler em inglês

Partilhar via


Códigos de erro da API de serviço de solicitação

O Microsoft Entra Verified ID inclui a API REST do Serviço de Solicitação que permite emitir e verificar uma credencial. Este artigo especifica os códigos de erro para a API de serviço de solicitação.

Objeto de erro

Durante a visualização pública, a API do Serviço de Solicitação retornou erros no formato a seguir.

{
  "requestId": "4bb6726f77af7623ab52962323016442",
  "date": "Thu, 28 Apr 2022 14:30:54 GMT",
  "mscv": "17ppwf3uxR10MfRR.1",
  "error": {
    "code": "client_request.invalid_include_qr_code",
    "message": "The request contains `includeQRCode`, but it is not boolean."
  }
}

Esse formato agora é alterado para o seguinte para permitir um tratamento de erros mais simples e um melhor suporte para solução de problemas. No novo formato, o código de erro externo e os campos de mensagem têm valores padronizados, enquanto o objeto fornece detalhes sobre o que causou o innererror erro.

{
  "requestId": "782628eb-503a-4978-84f2-d7c634f25b15",
  "date": "Fri, 29 Apr 2022 11:20:19 GMT",
  "mscv": "QbBLwF7XAp0dt4Lw.1",
  "error": {
    "code": "badRequest",
    "message": "The request is invalid.",
    "innererror": {
      "code": "badOrMissingField",
      "message": "The request contains `includeQRCode`, but it is not boolean.",
      "target": "includeQRCode"
    }
  }
}
Propriedade Type Description
requestId string Um ID de solicitação gerado automaticamente.
date data A hora do erro.
mscv string Código interno da Microsoft.
error Erro O objeto de erro externo

Tipo de erro

O error objeto agora está correspondendo ao código de status HTTP retornado da chamada de API para permitir um tratamento de erros mais fácil para os desenvolvedores.

Propriedade Type Description
code string O código de erro de retorno correspondente ao código de status HTTP.
message string Uma mensagem de erro padronizada que também depende do código de status HTTP retornado.
innererror Erro interno Forneça detalhes sobre o que causou o erro.

Códigos de erro e mensagens

A seguir estão os possíveis valores de nível superior que mapeiam para os diferentes códigos de code status HTTP retornados.

Código de status HTTP code mensagem
400 badRequest O pedido é inválido.
401 não autorizado O recurso solicitado requer autenticação
403 proibido Faltam permissões para atender a essa solicitação.
404 notFound O recurso solicitado não existe.
405 methodNotAllowed O método solicitado não é permitido no recurso solicitado.
406 nãoAceitável O formato de resposta solicitado não é suportado.
408 requestTimeout O tempo limite da solicitação expirou.
409 conflito O servidor não pode atender à solicitação devido a um conflito de servidor.
410 Foi-se O recurso solicitado não está mais disponível.
411 contentLengthRequired O cabeçalho Content-Length está ausente.
412 pré-condiçãoFalhou Falhou uma pré-condição para este pedido.
413 carga útilTooLarge A carga útil é demasiado grande.
414 uriTooLong O URI é muito longo.
415 sem suporteMediaType O tipo de mídia especificado não é suportado.
416 intervaloNotSatisfiable O intervalo de dados solicitado não pode ser satisfeito.
417 expectativaFalhou O cabeçalho Expect não pôde ser satisfeito.
421 mal direcionadoRequest Não é possível produzir uma resposta para esta solicitação.
422 unprocessableEntity A solicitação contém erros semânticos.
423 bloqueado O recurso de origem ou destino está bloqueado.
429 tooManyRequests Demasiados pedidos, tente novamente mais tarde.
431 requestHeaderFieldsTooLarge O campo de cabeçalho da solicitação é muito grande.
500 internalServerError Ocorreu um erro genérico no servidor.
501 nãoImplementado O servidor não suporta a função solicitada.
502 badGateway resposta incorreta recebida de outro gateway.
503 serviçoIndisponível O servidor está temporariamente indisponível, tente novamente mais tarde.
504 gatewayTimeout Tempo limite recebido de outro gateway.
507 armazenamento insuficiente Não é possível salvar dados para a solicitação.

Tipo de erro interno

O objeto de erro interno contém detalhes específicos de erro úteis para o desenvolvedor para ajudar a investigar a falha atual.

{
  "requestId": "782628eb-503a-4978-84f2-d7c634f25b15",
  "date": "Fri, 29 Apr 2022 11:20:19 GMT",
  "mscv": "QbBLwF7XAp0dt4Lw.1",
  "error": {
    "code": "badRequest",
    "message": "The request is invalid.",
    "innererror": {
      "code": "badOrMissingField",
      "message": "The request contains `includeQRCode`, but it is not boolean.",
      "target": "includeQRCode"
    }
  }
}
Propriedade Type Description
code string O código de erro interno. Contém um código padronizado, com base no tipo de erro
message string A mensagem de erro interna. Contém uma mensagem detalhada do erro. Neste exemplo, o includeQRCode campo é do tipo errado.
target string Opcional. Target contém o campo na solicitação que está causando esse erro. Este campo é opcional e pode não estar presente, dependendo do tipo de erro.

Códigos de erro internos

Código Description
badOrMissingField retornado quando ocorrerem problemas de validação na solicitação. O target campo contém o campo na solicitação que está causando o problema.
notFound retornado quando um recurso que o cliente está solicitando não é encontrado. O target campo contém o nome/id do recurso que não foi encontrado.
tokenError retornou para quaisquer problemas de validação em tokens como JWT e afins. O target campo contém o nome do token que causa o problema, quando aplicável.
transientError devolvido para todos os casos em que o cliente poderá obter uma resposta bem-sucedida se repetir o pedido numa fase posterior. Um exemplo comum de quando esse código é retornado é quando um código HTTP 429 é retornado

Próximos passos