Códigos de erro da API do Serviço de Solicitação

Artigo
10/29/2023

Observação

A ID Verificada do Microsoft Entra agora é ID Verificada do Microsoft Entra e faz parte da família de produtos Microsoft Entra. Saiba mais sobre a família Microsoft Entra de soluções de identidade e comece a usar o centro de administração unificado Microsoft Entra.

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

Objeto de erro

Durante a versão prévia 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 habilitar o tratamento de erro mais simples e o melhor suporte para a 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 innererror fornece detalhes sobre o que causou o 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	Descrição
`requestId`	Cadeia de caracteres	Uma ID da solicitação gerada automaticamente.
`date`	date	A hora do erro.
`mscv`	string	Código interno da Microsoft.
`error`	Erro	O objeto de erro externo

Tipo de erro

O objeto error agora está correspondendo ao Código de Status HTTP retornado da Chamada à API para facilitar o tratamento de erro para desenvolvedores.

Propriedade	Type	Descrição
`code`	string	O código de erro retornado que corresponde 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`	Innererror	Forneça detalhes sobre o que causou o erro.

Códigos de erro e mensagens

Veja a seguir os possíveis valores code de nível superior mapeados para os diferentes códigos de status HTTP retornados.

Código de status HTTP	code	message
400	badRequest	A solicitação é inválida.
401	não autorizado	O recurso solicitado requer a autenticação
403	forbidden	Permissões ausentes 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 especificado.
406	notAcceptable	Não há suporte para o formato de resposta solicitado.
408	requestTimeout	Tempo limite da solicitação excedido.
409	conflito	O servidor não pode atender à solicitação devido a um conflito de servidor.
410	gone	O recurso solicitado não está mais disponível.
411	contentLengthRequired	O cabeçalho Content-Length está ausente.
412	preconditionFailed	Falha na pré-condição dessa solicitação.
413	payloadTooLarge	O conteúdo é muito grande.
414	uriTooLong	O URI é muito longo.
415	unsupportedMediaType	Não há suporte para o tipo de mídia especificado.
416	rangeNotSatisfiable	O intervalo solicitado de dados solicitados não pode ser atendido.
417	expectationFailed	O cabeçalho Expect não pôde ser atendido.
421	misdirectedRequest	Não é possível produzir uma resposta para essa solicitação.
422	unprocessableEntity	A solicitação contém erros semânticos.
423	bloqueado	O recurso de origem ou de destino está bloqueado.
429	tooManyRequests	Excesso de solicitações. Tente novamente mais tarde.
431	requestHeaderFieldsTooLarge	O campo do cabeçalho da solicitação está muito grande.
500	internalServerError	Erro genérico no servidor.
501	notImplemented	O servidor não dá suporte à função solicitada.
502	badGateway	Resposta incorreta recebida de outro gateway.
503	serviceUnavailable	Servidor não disponível temporariamente, tente novamente mais tarde.
504	gatewayTimeout	Tempo limite recebido de outro gateway.
507	insufficientStorage	Não é possível salvar dados para a solicitação.

Tipo de erro interno

O objeto de erro interno contém detalhes específicos do 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	Descrição
`code`	string	O código de erro interno. Contém um código padronizado, com base no tipo do erro
`message`	string	A mensagem de erro interna. Contém uma mensagem detalhada do erro. Neste exemplo, o campo `includeQRCode` é do tipo errado.
`target`	string	Opcional. O destino contém o campo na solicitação que está causando esse erro. Esse campo é opcional e pode não estar presente, dependendo do tipo de erro.

Códigos de erro internos

Código	Descrição
`badOrMissingField`	retornado quando ocorrem problemas de validação na solicitação. O campo `target` 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 campo `target` contém o nome/a ID do recurso que não foi encontrado.
`tokenError`	retornado para problemas de validação em tokens como JWT e similares. O campo `target` contém o nome do token que causa o problema, quando aplicável.
`transientError`	retornado para todos os casos em que o cliente poderá obter uma resposta bem-sucedida se tentar novamente a solicitação em uma fase posterior. Um exemplo comum de quando esse código é retornado é quando um código HTTP 429 é retornado

Compartilhar via