# Common Issues ## Connection issues
401 Unauthorized or 403 Forbidden error Your API authentication is missing or incorrect. **Fix:** 1. Check your API documentation for the correct authentication header format (API Key, Bearer token, Basic auth, etc.) 2. Verify your authentication credentials (API key, token, username/password) are correct and not expired 3. In **Request headers**, add the authentication header exactly as specified by your API (e.g., `Authorization: Bearer YOUR_TOKEN`) 4. If using Basic auth, encode your credentials as base64 and use: `Authorization: Basic BASE64_ENCODED_CREDENTIALS` 5. Test your API with a tool like Postman to confirm authentication works before retrying in Coupler.io {% hint style="warning" %} Never paste your actual API key or token in test messages or screenshots. Always keep credentials secure in Coupler.io's header field. {% endhint %}
404 Not Found error The URL or endpoint path is incorrect. **Fix:** 1. Double-check the URL in **JSON URL** — verify the endpoint path matches your API documentation 2. If the API requires query parameters, add them in **URL query parameters** (e.g., `api_version=v2&filter=active`) 3. Test the URL in your browser or with Postman to confirm it's accessible and returns data 4. Some APIs require specific headers to work correctly — check your API docs and add any required headers in **Request headers**
Connection timeout or slow response The API is taking too long to respond. **Fix:** 1. If the API has pagination, use query parameters to limit results: `?limit=100&offset=0` instead of requesting all data at once 2. Add **Retries Count** and **Retries Delay** to automatically retry failed requests: try `3` retries with `2000` ms (2-second) delay 3. Check if the API has rate limits — space out your data flow runs or use a filter to request only recent data 4. Test the URL directly in Postman to see response time and confirm the API is responding normally 5. If the API consistently times out, check with your API provider if there are performance issues or service limits
SSL certificate or HTTPS error There's an issue with the API's SSL certificate. **Fix:** 1. Verify the URL uses `https://` (not `http://`) 2. Confirm the API endpoint is publicly accessible and has a valid SSL certificate 3. Test the URL in your browser — if your browser shows a security warning, contact the API provider 4. If you're using a self-signed certificate or internal API, contact Coupler.io support for assistance
## Missing data
No data imported or empty result The API returned data, but Coupler.io didn't import anything. **Fix:** 1. Check the [**Path** setting](https://docs.coupler.io/sources/category/files-and-tables/json/best-practices/how-to-define-the-path-for-selecting-json-objects) — if your JSON response has nested objects (e.g., `{ "data": { "users": [...] } }`), set **Path** to `data.users` to extract the array 2. If the API returns an object instead of an array, Coupler.io may not import it correctly — contact support with a sample of the API response 3. Verify the API is returning data by testing the URL with Postman or your browser 4. Check that your authentication headers are correct (see Connection issues above) 5. If using POST or PUT, confirm your **Request body** is in valid YAML format and matches what the API expects
Only partial data imported You're getting some data but not all rows. **Fix:** 1. If the API paginates results, you're likely only getting the first page. Check the API response for `page`, `offset`, `next`, or similar pagination fields 2. Create multiple data flows, one for each page (e.g., `?page=1`, `?page=2`, etc.), then use **Append** transformation to combine them 3. Or, check if the API supports a `limit` or `per_page` parameter to return all results in one request (e.g., `?limit=10000`) 4. If you set **Columns** to specific column names, verify the spelling matches the API response exactly (column names are case-sensitive)
Columns are missing or data looks truncated Some columns from the API response are not appearing in your destination. **Fix:** 1. If you manually set **Columns**, you may have omitted some columns. Leave **Columns** blank to import all available columns 2. Check if the **Columns** field has a typo or case mismatch — JSON column names are case-sensitive 3. Use Postman or your browser to inspect the raw API response and confirm all columns are present 4. If the API returns very long text in a column, it may be truncated in Google Sheets — this is a sheet limitation, not a Coupler.io issue
## Permission errors
Cannot access the destination (Google Sheets, BigQuery, etc.) Coupler.io can't write data to your destination. **Fix:** 1. Verify you've authenticated Coupler.io with your destination (Google Sheets, BigQuery, etc.) 2. Check that your destination account has write permissions to the specific sheet or table 3. If using a shared sheet, ensure you have edit access, not just view access 4. For BigQuery, confirm your account has the `bigquery.dataEditor` role on the target dataset 5. Re-authenticate your destination by disconnecting and reconnecting it in Coupler.io settings
## Data discrepancies
Data types are incorrect (numbers as text, dates formatted wrong, etc.) Coupler.io or your destination is interpreting columns as the wrong data type. **Fix:** 1. In Google Sheets, use **Format** > **Number** to set the correct format for each column (Number, Currency, Date, etc.) 2. Check the API response in Postman — if the API returns numbers as strings (e.g., `"123"` instead of `123`), this is an API issue 3. Some APIs return dates as timestamps (Unix time) — convert them in your destination sheet using formulas or post-import transformations 4. If a column should be numeric but appears as text, check for leading spaces or special characters in the API response
Duplicate rows appearing Your destination contains multiple copies of the same rows. **Fix:** 1. Check if you're running multiple data flows to the same destination — if so, they may both be appending the same data 2. If pagination is involved, verify each page query is unique (e.g., `?page=1`, `?page=2`) so you're not fetching the same rows twice 3. If scheduled runs are stacking data, use **Replace** mode instead of **Append** to overwrite previous data 4. Check if the API itself is returning duplicates by testing with Postman
Data is not refreshing or showing stale results Your destination shows old data even after running the data flow. **Fix:** 1. Confirm the data flow ran successfully — check the **Run history** in Coupler.io 2. If using **Append** mode, old data won't be removed. Clear the destination manually or use **Replace** mode to overwrite 3. If scheduled, verify the schedule is set up correctly and hasn't been paused 4. Check if the API itself is returning fresh data by testing with Postman 5. Some data sources have cache delays — if the API caches responses, wait a few minutes before checking for updates
## Rate limits
429 Too Many Requests or rate limit error You're hitting the API's rate limit. **Fix:** 1. Check your API documentation for rate limit details (requests per minute/hour) 2. Add **Retries Count** and **Retries Delay** to auto-retry: use `5` retries with `5000` ms (5-second) delay between retries 3. Space out scheduled data flow runs — if you have multiple flows hitting the same API, stagger their schedules 4. Use query parameters to request smaller batches of data, or use pagination with longer intervals between pages 5. If you're testing frequently, reduce test runs — every manual run counts against your rate limit 6. Contact the API provider to request a higher rate limit if your use case requires frequent syncs
Request gets blocked or returned as "forbidden" The API is rejecting your requests, possibly due to rate limiting or suspicious activity detection. **Fix:** 1. Add a User-Agent header in **Request headers** to identify your requests: `User-Agent: Coupler.io/1.0` 2. Increase **Retries Delay** to add longer wait times between retries, signaling you're a legitimate client 3. Space out your data flow schedules so you're not hammering the API with rapid requests 4. Check if the API uses IP whitelisting — if so, contact support to get Coupler.io's IP addresses whitelisted 5. Some APIs require additional headers or rate-limit-specific settings — check their docs