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	Missing, invalid, or revoked API key
forbidden	The request is authenticated, but access is not allowed (e.g., resource belongs to a different user)

Example

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

---

Request Structure & Validation Errors

Code	Meaning
invalid_request	Malformed, missing, or invalid parameters
method_not_allowed	Unsupported HTTP method
invalid_payload	JSON body is missing required fields or contains invalid values
not_found	The requested resource does not exist

Example

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

---

Quota & Rate Limiting Errors

QRForge enforces both per‑minute and daily rate limits.

Code	Meaning
rate_limit_minute	Too many requests in the current minute window
rate_limit_day	Daily quota exceeded

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
resource_archived	The requested resource exists but is archived and cannot be interacted with

Example

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

---

Internal Errors

These indicate unexpected platform issues.

Code	Meaning
internal_error	A backend or infrastructure error occurred

Example

{
  "ok": false,
  "code": "internal_error",
  "message": "Internal server error. Please try again later."
}

---

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_limit_minute.
• 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