Errors

Service errors

Every ProveIDApiClient call returns .failure(ErrorResponse) when it fails. ErrorResponse.error holds the HTTP status code and the response body:

case .failure(let error):
    if case let .error(statusCode, data, _, underlying) = error {
        let body = data.flatMap { try? JSONSerialization.jsonObject(with: $0) as? [String: Any] }
        let message = body?["message"] as? String ?? underlying.localizedDescription
        showError(statusCode, message)
    }

HTTP	Meaning
400	Invalid request (e.g. a missing or wrong field)
401	Session invalid or expired; get a new token
403	Not allowed
404	Record not found
500	Server error

Show the message field of the response body to the user where it helps; it explains why the request was rejected.

Document detection

cardDetectionFailed(wrapperErrorsModel:) tells you why the document could not be captured. Use it to guide the user:

Field	When false
isWidthHeightRatioEligible	The document is held at an angle or not fully visible
isAreaRatioEligible	The document is too far (areaErrorRatio < 1) or too close
isInsideOfHint	The document is outside the frame hint (with captureOnlyInHint)
isHologramScoreEligible	Hologram glare
isGlareScoreEligible	Glare on the document
isImageSharpnessRatioEligible	The image is blurry

cardType gives the detected document type. If it is not in cardTypeList, a different document is shown; if it is the other side of the expected document (e.g. .NEW_ID_BACK while capturing the front), ask the user to turn it over.

NFC

PassportReaderCallback.error(error:) and errorMessage receive a TagError:

Error	Meaning	What to do
InvalidMRZKey	Serial number, date of birth or expiry date doesn’t match the document	Have the user confirm the details again
ConnectionError	The connection dropped	Hold the document still and try again
AuthenticationFailed	The document moved away from the phone	Remove the case, hold the document still and try again
ActiveAuthNotSupportedForPassport	The document doesn’t support active authentication	Read again without a nonce (nil)
ChipAuthenticationFailed	Chip authentication failed	Try again; check your ChipAuthenticationBackend
UserCanceled	The user closed the NFC sheet	Offer to try again
SessionTimeout	Reading took too long	Try again
NFCNotSupported	The device can’t read NFC	Hide the NFC step
InvalidTag	The card read is not an ID document (e.g. a credit card)	Scan the right document
MoreThanOneTagFound	More than one card is near the phone	Keep only the document near the phone
InvalidDocumentNumber, InvalidBirthDate, InvalidExpireDate	A detail passed to read is invalid	Have the user correct it
DeviceThermalStateIsCritical	The device is too hot	Try again later
ResponseError, UnexpectedError	Unexpected error	Try again; contact Prove ID support if it persists

Return suppressError: true from errorMessage for errors you handle in your own screen (for example ConnectionError), so they aren’t shown as an error on the NFC sheet.