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}`);
}