Edit

Request Service API error codes

  • Article

Microsoft Entra Verified ID includes the Request Service REST API that allows you to issue and verify a credential. This article specifies the error codes for the Request Service API.

Error object

During public preview, the Request Service API returned errors in the following format.

{
  "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."
  }
}

This format is now changed into the following to enable both simpler error handling and better support for troubleshooting. In the new format, the outer error code and message fields have standardized values while the innererror object provide details on what caused the error.

{
  "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"
    }
  }
}
Property Type Description
requestId string An autogenerated request ID.
date date The time of the error.
mscv string Internal Microsoft code.
error Error The outer error object

Error type

The error object is now matching the HTTP Status Code returned from the API Call to enable easier error handling for developers.

Property Type Description
code string The return error code matching the HTTP Status Code.
message string A standardized error message that is also dependent on the HTTP status code returned.
innererror Innererror Provide details on what caused the error.

Error codes and messages

The following are the possible top level code values that maps to the different HTTP status codes returned.

HTTP Status Code code message
400 badRequest The request is invalid.
401 unauthorized The requested resource requires authentication
403 forbidden Missing permissions to fulfill this request.
404 notFound The requested resource doesn't exist.
405 methodNotAllowed The requested method isn't allowed on the requested resource.
406 notAcceptable Requested response format not supported.
408 requestTimeout The request timed out.
409 conflict The server can't fulfill the request due to a server conflict.
410 gone The requested resource is no longer available.
411 contentLengthRequired The Content-Length header is missing.
412 preconditionFailed A precondition for this request failed.
413 payloadTooLarge The payload is too large.
414 uriTooLong The URI is too long.
415 unsupportedMediaType The specified media type is unsupported.
416 rangeNotSatisfiable The requested range of data requested can't be satisfied.
417 expectationFailed The Expect header couldn't be satisfied.
421 misdirectedRequest Unable to produce a response for this request.
422 unprocessableEntity The request contains semantic errors.
423 locked The source or destination resource is locked.
429 tooManyRequests Too many requests, try again later.
431 requestHeaderFieldsTooLarge The request header field is too large.
500 internalServerError A generic error has occurred on the server.
501 notImplemented The server doesn't support the requested function.
502 badGateway bad response received from another gateway.
503 serviceUnavailable The server is temporarily unavailable, please try again later.
504 gatewayTimeout Time out received from another gateway.
507 insufficientStorage Unable to save data for the request.

Inner error type

The inner error object contains error specific details useful to the developer to help investigate the current failure.

{
  "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"
    }
  }
}
Property Type Description
code string The internal error code. Contains a standardized code, based on the type of the error
message string The internal error message. Contains a detailed message of the error. In this example, the includeQRCode field is of the wrong type.
target string Optional. Target contains the field in the request that is causing this error. This field is optional and may not be present, depending on the error type.

Inner error codes

Code Description
badOrMissingField returned when validation issues on the request occur. The target field contains the field in the request that is causing the issue.
notFound returned when a resource the client is requesting isn't found. The target field contains the resource name/id that isn't found.
tokenError returned for any validation issues on tokens like JWT and the likes. The target field contains the token name causing the issue, when applicable.
transientError returned for all the cases where the client might be able to get a successful response if they retry the request at a later stage. A common example of when this code is returned is when an HTTP 429 code is returned back

Next steps