Fix AAMVA_NOT_VALID After PDF417 Decoding

What the Failure Means

AAMVA_NOT_VALID is different from an unreadable image. A PDF417 symbol was decoded, but its payload did not contain a usable AAMVA driver-license record with the required structure.

A Reliable Recovery Path

Confirm that the uploaded image is the back of a US driver license or State ID, reject unrelated PDF417 symbols, and route persistent cases to document review. Consult the PDF417 error reference for status codes and use the scanner with fictional or authorized samples while tuning capture guidance.

Where This Workflow Fits

• Correct document type: Validate this condition before the image leaves the capture screen.
• Back side submitted: Include this check in support guidance and quality monitoring.
• AAMVA header present: Include this check in support guidance and quality monitoring.

Handle the Result Explicitly

Treat capture errors as application states. Never substitute guessed identity values when the barcode cannot be validated.

Prerequisite: A server-side API integration and a capture UI that can request a new license-back image

if response.status_code == 422:
    error = response.json().get("error")
    if error == "AAMVA_NOT_VALID":
        return {
            "action": "review_document",
            "message": "Use the back of a US driver license or State ID.",
        }

Example Recoverable Error

This illustrative error contains no personal data. Use the error code, rather than free-form text, to select the next application action.

{
  "success": false,
  "error": "AAMVA_NOT_VALID",
  "message": "Upload a clear image of the complete back of the US driver license or State ID."
}