Solicitar códigos de erro da API de Serviço

Artigo
01/31/2025

A ID verificada do Microsoft Entra 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 do Serviço de Solicitação.

Objeto error

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 habilitar o tratamento de erros mais simples e o melhor suporte para solução de problemas. No novo formato, o erro de externo campos de código e 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	Tipo	Descrição
`requestId`	corda	Uma ID de solicitação gerada automaticamente.
`date`	data	A hora do erro.
`mscv`	corda	Código interno da Microsoft.
`error`	de erro do	O objeto de erro externo

Tipo de erro

O objeto error agora está correspondendo ao código de status HTTP retornado da Chamada de API para habilitar o tratamento de erros mais fácil para desenvolvedores.

Propriedade	Tipo	Descrição
`code`	corda	O código de erro de retorno que corresponde ao código de status HTTP.
`message`	corda	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 de code de nível superior que são mapeados para os diferentes códigos de status HTTP retornados.

Código de status HTTP	código	Mensagem
400	badRequest	A solicitação é inválida.
401	Desautorizado	O recurso solicitado requer autenticação
403	proibido	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 solicitado.
406	Não aceitável	Não há suporte para o formato de resposta solicitado.
408	requestTimeout	A solicitação atingiu o tempo limite.
409	conflito	O servidor não pode atender à solicitação devido a um conflito de servidor.
410	sumido	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	O tipo de mídia especificado não tem suporte.
416	rangeNotSatisfiable	O intervalo solicitado de dados solicitados não pode ser atendido.
417	expectationFailed	O cabeçalho esperado 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	trancado	O recurso de origem ou destino está bloqueado.
429	tooManyRequests	Muitas solicitações, tente novamente mais tarde.
431	requestHeaderFieldsTooLarge	O campo de cabeçalho de solicitação é muito grande.
500	internalServerError	Ocorreu um 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	O servidor está temporariamente indisponível, 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	Tipo	Descrição
`code`	corda	O código de erro interno. Contém um código padronizado, com base no tipo do erro
`message`	corda	A mensagem de erro interna. Contém uma mensagem detalhada do erro. Neste exemplo, o campo `includeQRCode` é do tipo errado.
`target`	corda	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/ID do recurso que não foi encontrado.
`tokenError`	retornado para quaisquer problemas de validação em tokens como JWT (Token Web JSON) 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 um estágio posterior. Um exemplo comum de quando esse código é retornado é quando um código HTTP 429 é retornado de volta

Próximas etapas

especificação da API de Emissão de
especificação da API de Apresentação

Compartilhar via