Skip to main content

​
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"
  }
}
FieldDescription
codeMachine-readable error code
messageHuman-readable description
doc_urlLink to relevant documentation
request_idUnique ID for debugging (include this when contacting support)

​
Error codes

HTTP StatusCodeDescription
400invalid_requestThe request body is malformed or missing required fields
401unauthorizedMissing or invalid API key
403forbiddenThe API key does not have the required scope
404not_foundThe requested resource does not exist
409conflictA resource with that identifier already exists
422unprocessable_entityThe request is valid but cannot be processed (e.g., plan limit reached)
429rate_limit_exceededToo many requests — see Rate Limiting
500internal_errorAn 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']}")