Choosing SVG or PNG for QR Codes: Avoid Resolution Issues and Scan Failures

The decision between SVG and PNG for QR code generation depends entirely on where the end user will encounter the image. Choosing the wrong format leads to either blurred edges that fail to scan on physical media or unnecessarily large payloads that slow down mobile page loads.

Use SVG for print and high-DPI displays

When a QR code is destined for posters, product packaging, or large-scale signage, raster formats like PNG are a liability. Because PNGs are composed of a fixed grid of pixels, scaling them up to fit a physical medium introduces interpolation artifacts and blurriness. This degradation of the "modules" (the black and white squares) often results in scan failures because the scanner cannot clearly distinguish the boundary between a module and the background.

The /qr.svg endpoint returns an image/svg+xml response. Because SVGs are vector-based, they describe the QR code as a series of mathematical paths rather than pixels. This allows a graphic designer or a printing press to scale the image to any size—from a business card to a billboard—without any loss of edge definition.

For backend developers, integrating the SVG endpoint ensures that the asset remains resolution-independent. If your application supports a "Download for Print" feature, the SVG format is the only correct choice to avoid the common failure mode of pixelated, unscannable printed codes.

Prefer PNG for web and mobile screens

For digital-only deployments—such as in-app authentication, mobile websites, or social media shares—the overhead of a vector file is rarely justified. PNGs are optimized for immediate browser rendering and have broader compatibility across legacy mobile viewers.

The /qr endpoint returns an image/png response. For a developer, this means the image can be served directly in an <img> tag or cached via a CDN without needing client-side SVG rendering logic. The primary trade-off here is the fixed resolution. While you can increase the image size using the scale parameter, the resulting file is still a raster.

In a mobile environment, payload size directly impacts the Time to Interactive (TTI). A PNG is generally more performant for the rapid delivery of small-to-medium sized codes on a screen, where the high-density pixels of modern smartphones make the precision of a vector file invisible to the user.

Select error correction level H when overlaying logos

QR codes contain redundant data to ensure they remain readable even if part of the image is obscured or damaged. The API provides four error correction levels: L, M, Q, and H.

The critical decision occurs when you plan to place a brand logo in the center of the QR code. Doing so effectively "destroys" a portion of the data modules. If you use level L (Low) or M (Medium), the amount of missing data caused by the logo will likely exceed the recovery capacity of the code, rendering it completely unscannable.

You must set the error parameter to H (High) for any QR code that will have visual elements overlaid. Level H provides the maximum redundancy, allowing the code to be recovered even with significant portions of the image missing. The trade-off is that the QR code becomes denser (more modules) to accommodate the extra redundancy, which may require a larger physical size to remain scannable by lower-end camera hardware.

Set module size and quiet-zone borders for physical media

A common failure mode in printed QR codes is the "bleed" effect, where the QR code is placed too close to other graphic elements or the edge of the paper. Scanners require a "quiet zone"—a blank border around the code—to distinguish the QR code from its surrounding environment.

To prevent scan failures, use the border parameter to define a sufficient quiet zone. If the border is too narrow, the scanner may fail to lock onto the alignment patterns. For print media, a larger border is safer to account for potential cropping or framing issues during the printing process.

Additionally, the scale parameter controls the module size in pixels. While a small scale might look fine on a 4K monitor, it can result in modules that are too small for a standard smartphone camera to resolve when printed. When generating assets for physical labels or tickets, increase the scale value to ensure each module is large enough to be captured clearly by a camera lens.

Ensure high contrast between foreground and background

QR scanners rely on the contrast difference between the dark (foreground) and light (background) parameters. While the API allows for custom 6-digit hex colors, choosing low-contrast pairings—such as a light grey foreground on a white background—will lead to intermittent scan failures, especially in poor lighting conditions.

The safest configuration is a dark foreground (e.g., 000000) and a light background (e.g., FFFFFF). If brand guidelines require custom colors, verify that the foreground is significantly darker than the background. If the contrast is too low, the scanner cannot reliably differentiate the modules, resulting in a "no code found" error for the end user.

Implementation Examples

Below are runnable examples for integrating these decisions into your backend.

Node.js Implementation

const axios = require('axios');
const fs = require('fs');

async function generateQRCode() {
  const API_KEY = 'your_api_key';
  const BASE_URL = 'https://routexapi.com';
  
  // Scenario: High-resolution SVG for print with high error correction for a logo
  const printParams = {
    data: 'https://example.com/product',
    scale: 10,
    border: 4,
    error: 'H',
    dark: '000000',
    light: 'FFFFFF'
  };

  try {
    const response = await axios({
      method: 'get',
      url: `${BASE_URL}/qr.svg`,
      params: printParams,
      headers: { 'Authorization': `Bearer ${API_KEY}` },
      responseType: 'arraybuffer'
    });

    fs.writeFileSync('print_qr.svg', response.data);
  } catch (error) {
    console.error('Error generating SVG:', error.message);
  }
}

generateQRCode();

Python Implementation

import requests

def generate_web_qr():
    api_key = "your_api_key"
    base_url = "https://routexapi.com/qr"
    
    # Scenario: Lightweight PNG for mobile web display
    params = {
        "data": "https://example.com/login",
        "scale": 5,
        "border": 2,
        "error": "M",
        "dark": "0033CC",
        "light": "FFFFFF"
    }
    
    headers = {
        "Authorization": f"Bearer {api_key}"
    }
    
    response = requests.get(base_url, params=params, headers=headers)
    
    if response.status_code == 200:
        with open("web_qr.png", "wb") as f:
            f.write(response.content)
    else:
        print(f"Failed to generate QR code: {response.status_code}")

generate_web_qr()