Partilhar via

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

  • Artigo

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 o tratamento mais simples de erros e um melhor suporte para solução de problemas. No novo formato, os campos de código de de erro de externa e 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 Tipo Descrição
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 objeto error 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 Tipo Descrição
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 Innererror Forneça detalhes sobre o que causou o erro.

Códigos de erro e mensagens

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

Código de status HTTP código 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 solicitados não pode ser satisfeito.
417 expectativaFalhou O cabeçalho Esperado 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 Tipo Descrição
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 campo includeQRCode é 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 Descrição
badOrMissingField retornado quando ocorrerem 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 JSON Web Token (JWT) e afins. O campo target contém o nome do token que está causando 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