Error Codes

Complete reference for all API error responses.

Error Response Format

All errors return JSON with this structure:

{
  "error": true,
  "message": "Human-readable error message",
  "code": "ERROR_CODE"
}

HTTP Status Codes

Status	Category	Description
400	Client Error	Invalid request parameters
401	Authentication	Invalid or missing API key
403	Authorization	Insufficient permissions
404	Not Found	Resource doesn't exist
429	Rate Limit	Too many requests
500	Server Error	Internal server error

Error Reference

400 Bad Request

data parameter required

{
  "error": true,
  "message": "data parameter required",
  "code": "MISSING_DATA"
}

Cause: The data parameter is missing from the request.

Solution: Include the data parameter with the content to encode.

---

Invalid size

{
  "error": true,
  "message": "Invalid size. Must be between 50 and 2000",
  "code": "INVALID_SIZE"
}

Cause: Size parameter is outside the allowed range.

Solution: Use a size between 50 and 2000 pixels.

---

Invalid format

{
  "error": true,
  "message": "Invalid format. Use 'png' or 'svg'",
  "code": "INVALID_FORMAT"
}

Cause: Unsupported output format specified.

Solution: Use png or svg for the format parameter.

---

Invalid color

{
  "error": true,
  "message": "Invalid color format. Use hex without #",
  "code": "INVALID_COLOR"
}

Cause: Color value is not a valid hex code.

Solution: Use 6-character hex without the # symbol (e.g., 4F46E5).

---

Data too long

{
  "error": true,
  "message": "Data exceeds maximum length of 2953 characters",
  "code": "DATA_TOO_LONG"
}

Cause: The data to encode exceeds QR code capacity.

Solution: Shorten your data or use a URL shortener.

---

Invalid error correction level

{
  "error": true,
  "message": "Invalid error correction level. Use L, M, Q, or H",
  "code": "INVALID_ERROR_CORRECTION"
}

Cause: Unrecognized error correction level.

Solution: Use one of: L, M, Q, or H.

---

Invalid URL

{
  "error": true,
  "message": "Invalid URL format",
  "code": "INVALID_URL"
}

Cause: The targetUrl for a dynamic link is not a valid URL.

Solution: Ensure the URL includes protocol (https://).

401 Unauthorized

API key required

{
  "error": true,
  "message": "API key required",
  "code": "MISSING_API_KEY"
}

Cause: No API key provided in the request.

Solution: Include your API key via Authorization header, X-API-Key header, or api_key parameter.

---

Invalid API key

{
  "error": true,
  "message": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Cause: The provided API key doesn't exist or is malformed.

Solution: Check your API key in the Dashboard and ensure it's copied correctly.

---

API key expired

{
  "error": true,
  "message": "API key has expired",
  "code": "EXPIRED_API_KEY"
}

Cause: The API key has been regenerated or the account is suspended.

Solution: Get your current API key from the Dashboard.

403 Forbidden

Feature requires upgrade

{
  "error": true,
  "message": "This feature requires a Pro plan",
  "code": "UPGRADE_REQUIRED"
}

Cause: Attempting to use a feature not available on your plan.

Solution: Upgrade your plan at Dashboard → Settings.

---

Dynamic link limit reached

{
  "error": true,
  "message": "Dynamic link limit reached for your plan",
  "code": "LINK_LIMIT_REACHED"
}

Cause: You've created the maximum number of dynamic links for your plan.

Solution: Delete unused links or upgrade your plan.

404 Not Found

Link not found

{
  "error": true,
  "message": "Link not found",
  "code": "LINK_NOT_FOUND"
}

Cause: The specified link ID doesn't exist or belongs to another user.

Solution: Verify the link ID is correct.

429 Too Many Requests

Rate limit exceeded

{
  "error": true,
  "message": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 60
}

Cause: Too many requests in the time window.

Solution: Wait for retryAfter seconds before retrying.

---

Monthly limit exceeded

{
  "error": true,
  "message": "Monthly request limit exceeded",
  "code": "MONTHLY_LIMIT_EXCEEDED",
  "resetDate": "2025-02-01T00:00:00Z"
}

Cause: You've used all requests for the current month.

Solution: Wait for the reset date or upgrade your plan.

500 Internal Server Error

Internal server error

{
  "error": true,
  "message": "Internal server error",
  "code": "INTERNAL_ERROR"
}

Cause: Something went wrong on our servers.

Solution: Retry the request. If the issue persists, contact support.

Handling Errors

JavaScript

async function generateQR(data) {
  const response = await fetch(
    `https://www.qrcodeapi.io/api/generate?data=${encodeURIComponent(data)}`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  );

  if (!response.ok) {
    const error = await response.json();
    
    switch (error.code) {
      case 'RATE_LIMIT_EXCEEDED':
        // Wait and retry
        await new Promise(r => setTimeout(r, error.retryAfter * 1000));
        return generateQR(data);
      
      case 'INVALID_API_KEY':
        throw new Error('Please check your API key');
      
      case 'UPGRADE_REQUIRED':
        throw new Error('This feature requires a Pro plan');
      
      default:
        throw new Error(error.message);
    }
  }

  return response.blob();
}

Python

import requests
import time

def generate_qr(data):
    response = requests.get(
        'https://www.qrcodeapi.io/api/generate',
        params={'data': data},
        headers={'Authorization': f'Bearer {API_KEY}'}
    )
    
    if response.status_code == 429:
        error = response.json()
        time.sleep(error.get('retryAfter', 60))
        return generate_qr(data)
    
    if not response.ok:
        error = response.json()
        raise Exception(error['message'])
    
    return response.content

Related

• Authentication - API key setup
• Rate Limits - Usage limits
• Support - Get help