A Koinly API connection error almost always comes down to a key that no longer works or an exchange that is blocking the request. It looks alarming, but the fix is usually quick: most failed connections are resolved by deleting the old key and reconnecting with a fresh read-only one. This guide walks through every common cause of a Koinly API connection error and the exact steps to clear each.
The reassuring part up front: an API error rarely means your data is lost or that Koinly is broken. It almost always means the connection between Koinly and your exchange needs to be re-established, which you can do yourself in minutes.
Disclaimer: This guide is for informational purposes only. Always consult a qualified CPA regarding your specific situation.
First: Confirm It Is Your Key, Not an Outage
Before recreating anything, rule out a service-wide problem.
- Check Koinly’s status page and X (Twitter) account for incident notices
- Check whether the exchange itself is having API problems, since Koinly cannot connect to an exchange that has disabled its API
- Try a different browser or incognito window to rule out a local issue
If everything is up but the connection still errors, the problem is the key or the exchange’s settings, and the rest of this guide applies.
Cause 1: Expired or Revoked Keys
This is the leading cause of Koinly API connection errors. Keys do not last forever. They expire, get revoked during exchange security events, or stop working after an exchange API update.
- Delete the broken connection in Koinly. Do not edit it. Remove it cleanly.
- Generate a fresh read-only key on the exchange. Create a new API key with read access only.
- Reconnect in Koinly and let it sync from scratch.
Cause 2: Wrong or Missing Permission Scopes
Sometimes the key is valid but lacks the read scope Koinly needs, or the exchange recently changed which permissions a key requires. The connection appears to succeed but pulls nothing, or pulls only some account types.
- Confirm the key has read access to every account type you use (spot, margin, futures, earn)
- Recreate the key if the exchange restructured its API permissions
- Some exchanges separate read permissions by product, so one key may not cover everything
Cause 3: IP Whitelisting and Rate Limits
A few exchanges require you to whitelist an IP address for API access, which can silently block Koinly. Others throttle requests when you sync repeatedly.
- Check whether the exchange’s API key settings include an IP allowlist, and if so, follow their guidance for third-party tools
- Stop hammering the sync button. Wait an hour after repeated attempts and retry once
Cause 4: When CSV Is the Smarter Move
If an exchange API is simply unreliable or the account is closed, stop fighting it and import a file instead.
- Export your complete transaction history as CSV from the exchange, covering all years
- Import that CSV into Koinly. Our Koinly CSV import walkthrough covers the export steps exchange by exchange
- Make sure you are not also running an API connection to the same exchange, or you will create duplicate transactions
A client kept seeing a connection error on his main exchange every time he opened Koinly. The exchange had rotated its API security weeks earlier and silently revoked his old key, so every sync failed. We deleted the dead connection, created a fresh read-only key, and the full history synced in minutes. For an older exchange that had since shut down, we imported a CSV. No bug in Koinly at all, just one revoked key and one closed account.
When the Connection Works but the Data Is Still Wrong
If your API finally connects but the totals or cost basis still look off, the connection was never the real issue. That points to tangled history: unmatched transfers, $0 cost basis from a missing source, or DeFi that classified inconsistently. If older trades are simply absent after a successful sync, our guide on finding and fixing Koinly missing transactions covers widening a partial pull, and if the symptom is a negative balance warning, that has its own dedicated fix.
When the data is genuinely tangled, a crypto tax service can reconcile the account, resolve the labeling and cost basis calls, and hand you a report you can file and defend. See our guide on getting human cleanup help for a messy Koinly or CoinTracker report.
Not sure your crypto taxes are right?
Talk to a Count On Sheep specialist. We will spot the costly errors before you file. No obligation.
Book My Free Review- Reviewed by Former Big 4 Accountants
- Keep your CPA
- No pressure, no sales pitch
Key Takeaways
- Bottom line: a Koinly API connection error is almost always an invalid key or a blocking exchange, not lost data or a software fault
- Start with the highest-yield fix: delete the broken connection and reconnect with a fresh read-only key, which clears most errors
- Keep keys read-only. Koinly never needs trade or withdrawal access, and extra scopes only add risk
- Watch for permission scopes, IP whitelists, and rate limits as secondary causes, and fall back to a full CSV export when an API stays unreliable
- Decision point: if the connection works but the numbers are still wrong, the issue is tangled history, and a crypto tax service can reconcile it before the deadline
Frequently Asked Questions
Why does Koinly show an API connection error?
The most common causes are an expired or revoked API key, a key missing the right read permission, an exchange that changed its API, an IP whitelist requirement, or rate limiting during peak season. Koinly cannot pull your data when the key is invalid or the exchange blocks the request, so it reports a connection error. A fresh read-only key fixes the majority of cases.
How do I fix an expired Koinly API key?
Delete the broken connection in Koinly rather than editing it, then generate a brand new read-only API key on the exchange and reconnect. API keys expire, get revoked during security events, or stop working when an exchange updates its API. Recreating the key from scratch resolves most Koinly connection errors.
What permissions does Koinly need for an API key?
Koinly only needs read access to import your transaction history. It never needs permission to trade or withdraw funds. When you create the key on the exchange, grant read-only scope and leave trade and withdrawal permissions off. A read-only key is both safer and fully sufficient for syncing your data into Koinly.
Can I use Koinly without connecting an API?
Yes. If the API keeps erroring, export your full transaction history as a CSV from the exchange and import that file into Koinly instead. CSV is the reliable fallback for exchanges with unstable APIs, closed accounts, or connections that will not reach far enough back in your history. Just avoid running both API and CSV on the same exchange.
When should I get help with Koinly API errors?
If you have recreated your keys, tried CSV imports, and cleared any rate limits but the data still will not reconcile, the real problem is usually tangled transaction history rather than the connection. A crypto tax service can reconcile the account and produce a correct, defensible report, which matters most when a filing deadline is close.