API Error Reference

QRForge uses a consistent, structured error format across all API endpoints.
Every error response includes an error code, a human‑readable message, and a unique request_id you can reference when contacting support.

---

Error Response Format

All error responses follow the same envelope:

{
  "ok": false,
  "version": "2025-11-14-v1",
  "request_id": "5e7c1cfa-e2c2-4b4f-b2b4-8aa25531c9ef",
  "code": "invalid_request",
  "message": "Missing required field: redirect_url"
}

Fields

Field	Description
ok	Always false for errors
version	API version string
request_id	Unique ID for tracking/debugging
code	Machine-readable error code
message	Human-readable description of what went wrong

---

Global Error Codes

Below is the full catalog of error codes used by the QRForge API v1.

---

Authentication & Authorization Errors

Code	Meaning
unauthorized	API key is missing, invalid, or revoked

Note: a request for a QR code or project you don't own returns 404 not_found, not a distinct "forbidden" code — this is deliberate, so a caller can't distinguish "doesn't exist" from "exists but isn't yours" by probing IDs.

Example

{
  "ok": false,
  "code": "unauthorized",
  "message": "Invalid or missing API key."
}

---

Request Structure & Validation Errors

Code	Meaning
invalid_request	Malformed, missing, or invalid parameters
invalid_payload	JSON body is missing required fields or contains invalid values
method_not_allowed	Unsupported HTTP method
not_found	The requested resource does not exist (or isn't yours — see above)
unsafe_url	The redirect_url (or a redirect rule's URL) was flagged unsafe by an automated safety check (HTTP 422 Unprocessable Entity)

Example

{
  "ok": false,
  "code": "invalid_request",
  "message": "Missing QR id (id or qr_id)."
}

---

Access & Entitlement Errors

Code	Meaning
api_access_disabled	API access is not enabled for your account
feature_disabled	The requested action isn't included in your current plan

Example

{
  "ok": false,
  "code": "feature_disabled",
  "message": "QR code creation is not included in your current plan."
}

---

Quota & Rate Limiting Errors

Code	Meaning
rate_limited	General per-key rate limit exceeded (applies to most read/write endpoints)
rate_limit_minute	QR-code creation: too many requests in the current minute window
rate_limit_day	QR-code creation: daily quota exceeded
quota_exceeded_qr	Your plan's QR-code creation limit has been reached (HTTP 402 Payment Required — an unusual but real status choice for this code)

Requests throttled by rate_limited include a Retry-After header (seconds).

Example

{
  "ok": false,
  "code": "rate_limit_minute",
  "message": "Too many requests this minute."
}

---

Project & Resource Access Errors

Code	Meaning
project_not_found	Project does not exist or does not belong to the API key owner

Example

{
  "ok": false,
  "code": "project_not_found",
  "message": "Project not found."
}

---

Internal Errors

These indicate unexpected platform issues — retry with backoff, and contact support with the request_id if they persist.

Code	Meaning
internal_error	A backend or infrastructure error occurred
config_error	The API key is misconfigured or its owning account could not be resolved. Contact support. (HTTP 500)

Example

{
  "ok": false,
  "code": "internal_error",
  "message": "Failed to validate API key."
}

config_error is returned when an API key's owner_uid doesn't resolve to a real user document — a data-integrity edge case such as an orphaned or misconfigured key:

{
  "ok": false,
  "code": "config_error",
  "message": "Owner user not found for API key."
}

---

Troubleshooting Guide

1. Verify your API key

• Ensure you're using the correct x-api-key.
• Confirm the key is active in the QRForge dashboard.

2. Validate request data

• Check required fields.
• Verify field formats (URLs must be http:// or https://).
• Ensure JSON is syntactically valid.

3. Respect rate limits

• Use retries with backoff on rate_limited, rate_limit_minute, and rate_limit_day — check for a Retry-After header where present.
• Do not exceed your daily quota.

4. Confirm project ownership

• Ensure the project_id belongs to your account.

---

Contact Support

If you encounter an error that is not documented here, please reach out with:

• request_id
• Endpoint you called
• Timestamp (UTC)
• Full response body

support@qrforge.link