Errors - QRKit API

Error format

All errors follow a consistent JSON structure:

{
  "error": {
    "code": "not_found",
    "message": "QR code not found",
    "doc_url": "https://docs.useqrkit.com/errors#not_found",
    "request_id": "req_abc123"
  }
}

Field	Description
`code`	Machine-readable error code
`message`	Human-readable description
`doc_url`	Link to relevant documentation
`request_id`	Unique ID for debugging (include this when contacting support)

Error codes

HTTP Status	Code	Description
`400`	`invalid_request`	The request body is malformed or missing required fields
`401`	`unauthorized`	Missing or invalid API key
`403`	`forbidden`	The API key does not have the required scope
`404`	`not_found`	The requested resource does not exist
`409`	`conflict`	A resource with that identifier already exists
`422`	`unprocessable_entity`	The request is valid but cannot be processed (e.g., plan limit reached)
`429`	`rate_limit_exceeded`	Too many requests — see Rate Limiting
`500`	`internal_error`	An unexpected error occurred on our end

Example responses

400 — Invalid request

{
  "error": {
    "code": "invalid_request",
    "message": "target.type must be one of: url, text, email, sms, wifi, event, vcard",
    "doc_url": "https://docs.useqrkit.com/errors#invalid_request",
    "request_id": "req_x1y2z3"
  }
}

401 — Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key",
    "doc_url": "https://docs.useqrkit.com/errors#unauthorized",
    "request_id": "req_a1b2c3"
  }
}

404 — Not found

{
  "error": {
    "code": "not_found",
    "message": "QR code 'qr_999' not found",
    "doc_url": "https://docs.useqrkit.com/errors#not_found",
    "request_id": "req_d4e5f6"
  }
}

422 — Plan limit reached

{
  "error": {
    "code": "unprocessable_entity",
    "message": "QR code limit reached for your plan. Upgrade to create more.",
    "doc_url": "https://docs.useqrkit.com/errors#unprocessable_entity",
    "request_id": "req_g7h8i9"
  }
}

429 — Rate limited

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "doc_url": "https://docs.useqrkit.com/errors#rate_limit_exceeded",
    "request_id": "req_j1k2l3"
  }
}

Handling errors

import requests

response = requests.post(
    "https://api.useqrkit.com/v1/qr-codes",
    headers={"Authorization": "Bearer qr_live_..."},
    json={"target": {"type": "url", "destination": "https://example.com"}},
)

if not response.ok:
    error = response.json()["error"]
    print(f"Error {response.status_code}: {error['code']} — {error['message']}")
    print(f"Request ID: {error['request_id']}")

const response = await fetch("https://api.useqrkit.com/v1/qr-codes", {
  method: "POST",
  headers: {
    Authorization: "Bearer qr_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    target: { type: "url", destination: "https://example.com" },
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  console.error(`Error ${response.status}: ${error.code} — ${error.message}`);
  console.error(`Request ID: ${error.request_id}`);
}

​Error format

​Error codes

​Example responses

​400 — Invalid request

​401 — Unauthorized

​404 — Not found

​422 — Plan limit reached

​429 — Rate limited

​Handling errors

Error format

Error codes

Example responses

400 — Invalid request

401 — Unauthorized

404 — Not found

422 — Plan limit reached

429 — Rate limited

Handling errors