My API or automated data import is failing — how do I fix it?

If your API, webhook, or email import is failing or has stopped fetching data, here's how to diagnose and fix the problem.

Understanding connection health

Every automated import (API connection, webhook) has a connection runner that fetches data on a schedule. You can see its health in Analytics → Data Import — look for the status badge and failure count next to each import.

Runner statuses

• "active" — running normally on schedule
• "paused" — temporarily paused by you or an admin
• "error" — stopped after too many consecutive failures (usually 3). Will NOT retry automatically — you need to fix the issue and re-enable it
• "disabled" — turned off permanently

Common failure causes and fixes

1. Authentication failure (401/403)

The API rejected your credentials. This is the most common cause.

• Check if your API key or token has expired — many vendor APIs rotate keys periodically
• Verify the credentials in your import configuration match what the vendor issued
• If using OAuth, the refresh token may have expired — you'll need to re-authenticate

2. Endpoint unreachable (timeout/connection refused)

The vendor's API server is down or your URL is wrong.

• Check the vendor's status page for outages
• Verify the API URL hasn't changed (vendors sometimes update API versions)
• The system will retry with exponential backoff (5min → 10min → 20min, up to 1 hour max)

3. Rate limiting (HTTP 429)

You're making too many requests to the vendor API.

• The system automatically backs off and retries
• If this keeps happening, increase the fetch interval in your import settings (e.g., from 15 minutes to 1 hour)

4. Data format changed

The vendor changed their API response structure.

• Your field mapping may no longer match — the timestamp or value fields may have moved
• Check if the vendor released a new API version
• You may need to reconfigure the import with the updated Swagger/OpenAPI specification

5. Partial failures (completed_with_errors)

Some data was imported but not all. This usually means:

• Some meter readings had invalid timestamps or values
• A new meter appeared in the source that isn't mapped yet
• Check the import details to see which specific readings failed and why

How the retry system works

When a fetch fails, the system uses exponential backoff:

• 1st failure: retries after 5 minutes
• 2nd failure: retries after 10 minutes
• 3rd failure: retries after 20 minutes After 3 consecutive failures, the runner status changes to "error" and stops retrying. At this point you need to:

1. Fix the underlying issue (credentials, URL, format)
2. Go to the import settings and re-enable the connection
3. The system will immediately attempt a new fetch

What are discovered meters?

When your import fetches data, the system discovers meter points from the source. These appear as "discovered meters" and need to be connected to your building's analytics meters before their data shows in charts. If you see staged readings but no chart data, check if the discovered meters are connected.

Using the AI Import Builder (Swagger/OpenAPI)

For REST API integrations, you can paste your vendor's Swagger/OpenAPI specification (YAML or JSON). The AI analyzes the spec and automatically configures:

• The correct authentication method (API key, Bearer token, OAuth)
• Which endpoints to call and how often
• How to extract timestamps and meter values from the response
• Field mapping from the vendor's format to the platform's format If the AI-configured import fails, check the "last fetch error" message — it usually tells you exactly which field or endpoint is causing the problem.