Issue Codes in API Responses

A successful Passport Photo API response may include an issues array. These codes describe conditions detected in the source or processed photo that your application should review.

An issue code is different from an HTTP or authentication error: the request may succeed and still return one or more photo issues.

Issue reference

Issue code	Meaning	Suggested user action
ISSUE_FACE_NOT_FOUND	No usable face was detected.	Upload a clear, single-person portrait with the complete face visible.
ISSUE_FACE_LIGHT_NOT_BALANCE	Lighting differs too much between the two sides of the face.	Face a soft, even light source and avoid strong side lighting.
ISSUE_FACE_BRIGHTNESS_BAD	The face is too dark or too bright.	Retake the photo in even light and avoid backlighting or direct flash.
ISSUE_PHOTO_SHARPNESS_BAD	The photo is blurred, out of focus, or lacks sufficient detail.	Hold the camera steady, focus on the face, and use a higher-resolution image.
ISSUE_EYEGLASSES_NOT_ALLOWED	Eyeglasses were detected where the selected specification does not allow them.	Remove the glasses and retake the photo.
ISSUE_EYEGLASSES_REFLECTION	Reflections on glasses may obscure the eyes.	Remove the glasses or change the lighting and camera angle.
ISSUE_SUNGLASSES_NOT_ALLOWED	Sunglasses obscure the face or eyes.	Remove the sunglasses and retake the photo.
ISSUE_HAT_NOT_ALLOWED	Unsupported headwear was detected.	Remove non-permitted headwear and retake the photo.
ISSUE_MASK_NOT_ALLOWED	A face mask is present. This issue code is marked as coming soon.	Ask the user to remove the mask and retake the photo when this check is enabled.
ISSUE_RELIGION_MASK_FOUND	A religious face covering was detected. This issue code is marked as coming soon.	Review the applicable photo requirements when this check is enabled.
ISSUE_EXPRESSION_NOT_NEUTRAL	The expression is not sufficiently neutral.	Look at the camera with a closed mouth and relaxed expression.
ISSUE_BOTTOM_NOT_FULL	The source image does not contain enough area below the subject.	Move the camera back and include the complete shoulders and upper torso.
ISSUE_LEFT_NOT_FULL	The left shoulder area is incomplete.	Move the camera back and keep both shoulders inside the frame.
ISSUE_RIGHT_NOT_FULL	The right shoulder area is incomplete.	Move the camera back and keep both shoulders inside the frame.
ISSUE_HEAD_YAW_OVER_THRESHOLD	The head is turned too far left or right.	Face the camera directly.
ISSUE_HEAD_PITCH_OVER_THRESHOLD	The head is tilted too far up or down.	Hold the head upright and look straight at the camera.
ISSUE_NOT_IN_COLOR	The submitted photo is not in color.	Upload an original color photo.
ISSUE_PHOTO_SPEC_NOT_EXIST	The requested photo specification was not found.	Query the current spec list and submit a valid specCode.

Recommended handling

Do not show raw issue codes to end users. Map each code to a short, localized instruction and decide whether your workflow should:

• continue with a warning;
• ask the user to review the preview; or
• require a new photo.

When multiple issues are returned, show the most actionable guidance first. For example, ask the user to retake a severely blurred photo before addressing smaller positioning issues.

Sensitivity overrides are available for selected checks. See Passport Photo API request fields.

Framing examples

The following example illustrates insufficient bottom, left-shoulder, or right-shoulder coverage.