Compartilhar via


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

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