Request Service API error codes
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.
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 |
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. |
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. |
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. |
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 |