From a66a1b1c334448c402068e7db57644849655051f Mon Sep 17 00:00:00 2001
From: Copilot <198982749+Copilot@users.noreply.github.com>
Date: Sun, 7 Dec 2025 19:31:16 +0100
Subject: [PATCH] Document KiCad's rejection of self-signed certificates
 (#1140)

* Initial plan

* Add documentation about KiCad self-signed certificate issues

Co-authored-by: jbtronics <5410681+jbtronics@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jbtronics <5410681+jbtronics@users.noreply.github.com>
---
 docs/troubleshooting.md       | 15 +++++++++++++++
 docs/usage/eda_integration.md | 10 ++++++++++
 2 files changed, 25 insertions(+)

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 74f9875e..a5b1b1c8 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -50,6 +50,21 @@ docker-compose logs -f
 
 Please include the error logs in your issue on GitHub, if you open an issue.
 
+## KiCad Integration Issues
+
+### "API responded with error code: 0: Unknown"
+
+If you get this error when trying to connect KiCad to Part-DB, it is most likely caused by KiCad not trusting your SSL/TLS certificate.
+
+**Cause:** KiCad does not trust self-signed SSL/TLS certificates.
+
+**Solutions:**
+- Use HTTP instead of HTTPS for the `root_url` in your KiCad library configuration (only recommended for local networks)
+- Use a certificate from a trusted Certificate Authority (CA) like [Let's Encrypt](https://letsencrypt.org/)
+- Add your self-signed certificate to the system's trusted certificate store on the computer running KiCad (the exact steps depend on your operating system)
+
+For more information about KiCad integration, see the [EDA / KiCad integration](../usage/eda_integration.md) documentation.
+
 ## Report Issue
 
 If an error occurs, or you found a bug, please [open an issue on GitHub](https://github.com/Part-DB/Part-DB-server).
diff --git a/docs/usage/eda_integration.md b/docs/usage/eda_integration.md
index f8988763..28386a91 100644
--- a/docs/usage/eda_integration.md
+++ b/docs/usage/eda_integration.md
@@ -22,6 +22,16 @@ This also allows to configure available and usable parts and their properties in
 Part-DB should be accessible from the PCs with KiCad. The URL should be stable (so no dynamically changing IP).
 You require a user account in Part-DB, which has permission to access the Part-DB API and create API tokens. Every user can have their own account, or you set up a shared read-only account.
 
+{: .warning }
+> **HTTPS with Self-Signed Certificates**
+> 
+> KiCad does not trust self-signed SSL/TLS certificates. If your Part-DB instance uses HTTPS with a self-signed certificate, KiCad will fail to connect and show an error like: `API responded with error code: 0: Unknown`.
+> 
+> To resolve this issue, you have the following options:
+> - Use HTTP instead of HTTPS for the `root_url` (only recommended for local networks)
+> - Use a certificate from a trusted Certificate Authority (CA) like [Let's Encrypt](https://letsencrypt.org/)
+> - Add your self-signed certificate to the system's trusted certificate store on the computer running KiCad (the exact steps depend on your operating system)
+
 To connect KiCad with Part-DB do the following steps:
 
 1. Create an API token on the user settings page for the KiCad application and copy/save it when it is shown. Currently, KiCad can only read the Part-DB database, so a token with a read-only scope is enough.