Troubleshooting

Troubleshooting (FAQ)

---

❌ API Key errors

• Symptom: Log shows ForbiddenError.
• Cause: API Key invalid or lacking permissions.
• Solution: Verify that your API Key is valid in Meteocat API portal.

✅ How to check your API Key permissions

You can test your API Key using Postman or any software that allows making HTTP GET requests. If you don't want to use Postman you can use the curl command, explained below the Postman method.

1. Download Postman (https://www.postman.com/downloads/) or a similar tool.
2. Create a new GET request.
3. Use the following URLs to test different resources of the Meteocat API:

• Towns: https://api.meteo.cat/referencia/v1/municipis?

  

• Variables: https://api.meteo.cat/xema/v1/variables/mesurades/metadades

  

• Symbols: https://api.meteo.cat/referencia/v1/simbols

  

• Quotas: https://api.meteo.cat/quotes/v1/consum-actual

  

  And you should see something like this:

  {
      "client": {
          "nom": "XXX XXXXXXXX"
      },
      "plans": [
          {
              "nom": "Referència Bàsic",
              "periode": "Mensual",
              "maxConsultes": 2000,
              "consultesRestants": 2000,
              "consultesRealitzades": 0
          },
          {
              "nom": "XDDE_250",
              "periode": "Mensual",
              "maxConsultes": 250,
              "consultesRestants": 249,
              "consultesRealitzades": 1
          },
          {
              "nom": "Quota",
              "periode": "Mensual",
              "maxConsultes": 300,
              "consultesRestants": 299,
              "consultesRealitzades": 1
          },
          {
              "nom": "Predicció_100",
              "periode": "Mensual",
              "maxConsultes": 100,
              "consultesRestants": 98,
              "consultesRealitzades": 2
          },
          {
              "nom": "XEMA_750 OD",
              "periode": "Mensual",
              "maxConsultes": 750,
              "consultesRestants": 747,
              "consultesRealitzades": 3
          }
      ]
  }
  

4. Add the required headers for authentication. For Meteocat API:

   • Content-Type: application/json
   • x-api-key: YOUR_API_KEY

5. Send the GET request.

   • If the request returns HTTP 200, the API Key has permission for that resource.
   • If it returns HTTP 403 (Forbidden), your API Key lacks the required permission.
   • If it returns HTTP 401 (Unauthorized), the API Key is invalid.

ℹ️ You can repeat these tests for each resource (towns, stations, variables, symbols, quotes) to check which permissions are enabled.

✅ Alternative to check your API Key permissions. Using the curl command.

Where to run the curl command it depends on where Home Assistant is installed.

• Option 1 — Home Assistant OS / Supervised / Docker (most common) 👉 From the Terminal / Home Assistant SSH add-on

  • Open Home Assistant
  • Go to:
  • Settings → Add-ons → Terminal & SSH
  • Open the terminal
  • Run: curl -i -H "X-Api-Key: YOUR_API_KEY" https://api.meteo.cat/xdde/v1/informes/comarques/your_region_id/year/month/day

  📌 Important: This is an example to test lightning data.

  • Replace YOUR_API_KEY with your actual API key.
  • Replace the URL for the proper URL you want to test (towns, variables, symbols, quotas, lightning).
  • If you want to test lightning data replace your_region_id and the year/month/day (yyyy/mm/dd)

  This will return something like:

  • ✔️ 200 OK → Correct, you have permissions
  • ❌ 403 Forbidden → You do NOT have permissions
  • ❌ 401 Unauthorized → Incorrect API key

• Option 2 — From any PC (Windows / Linux / Mac) You can also do this from your computer, without using Home Assistant.

  👉 On Windows (PowerShell):

  curl -Headers @{ "X-Api-Key" = "YOUR_API_KEY" } https://api.meteo.cat/xdde/v1/informes/comarques/your_region_id/year/month/day

  👉 On Windows (CMD):

  curl -H "X-Api-Key: YOUR_API_KEY" https://api.meteo.cat/xdde/v1/informes/comarques/your_region_id/year/month/day

  👉 On Linux / Mac:

  curl -i -H "X-Api-Key: YOUR_API_KEY" https://api.meteo.cat/xdde/v1/informes/comarques/your_region_id/year/month/day

  🔍 What to look for in the response

  • ✔️ OK case:

    HTTP/1.1 200 OK

    ...

    { JSON with data ... }

  • ❌ Case WITHOUT permissions:

    HTTP/1.1 403 Forbidden

    {"message ":"Forbidden"}

    → This confirms 100% that it's a permissions issue with the Meteocat plan, not the integration.

---

❌ Missing assets

• Symptom: Integration fails or towns/stations list is empty.

• Cause: Some assets/*.json files are missing.

• Solution: Use the Regenerate assets option from the configuration menu.

  

---

❌ Connection problems

• Symptom: Integration does not load data.
• Cause: Meteocat API unavailable.
• Solution: Wait and retry later. The integration will continue working with cached data.

---

⬅️ Uninstallation | ➡️ Contributing