Compartilhar via

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

  • Artigo

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

Próximas etapas