Skip to main content

Error Codes

Reference for all error codes returned by the QR Build API.

Error Response Format​

All errors follow a consistent format with success: false, an error code, and a human-readable message. Some errors include a details array with field-level information.

HTTP Status Code Reference​

StatusMeaning
200Success
201Created
400Bad Request (validation error)
401Unauthorized (auth error)
403Forbidden (permission/rate limit error)
404Not Found
500Internal Server Error

Error Response Format​

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": []
  }
}

Authentication Errors​

MISSING_API_KEY​

HTTP Status: 401 Unauthorized

Solution: Include your API key in the request headers.

INVALID_API_KEY​

HTTP Status: 401 Unauthorized

Solution: Check that your API key is correct and hasn't been revoked.

MISSING_API_KEY​

{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Provide it via X-API-Key header or Authorization: Bearer header."
  }
}

INVALID_API_KEY​

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Validation Errors​

VALIDATION_ERROR​

HTTP Status: 400 Bad Request

Solution: Check the details array for specific field errors.

INVALID_API_VERSION​

HTTP Status: 400 Bad Request

Solution: Use a valid version name in the QR-Version header, or omit it to use the default.

VALIDATION_ERROR​

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      {
        "field": "type",
        "message": "type is required"
      }
    ]
  }
}

INVALID_API_VERSION​

{
  "success": false,
  "error": {
    "code": "INVALID_API_VERSION",
    "message": "Invalid API version \"invalid\". Valid versions: 2026-02-16"
  }
}

Resource Errors​

QR_NOT_FOUND​

HTTP Status: 404 Not Found

Solution: Verify the QR code ID exists and belongs to your workspace.

Permission & Limit Errors​

LIMIT_EXCEEDED​

HTTP Status: 403 Forbidden

Solution: Delete unused QR codes or upgrade your plan. Rate limits reset on the 1st of each month.

FORBIDDEN​

HTTP Status: 403 Forbidden

Solution: Upgrade to a plan that includes API access.

Server Errors​

INTERNAL_ERROR​

HTTP Status: 500 Internal Server Error

Solution: Retry the request. If the problem persists, contact support.

QR_NOT_FOUND​

{
  "success": false,
  "error": {
    "code": "QR_NOT_FOUND",
    "message": "QR code not found"
  }
}

LIMIT_EXCEEDED​

{
  "success": false,
  "error": {
    "code": "LIMIT_EXCEEDED",
    "message": "Dynamic QR code limit exceeded for this workspace"
  }
}

FORBIDDEN​

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "API access is not available for this plan"
  }
}

INTERNAL_ERROR​

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}