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

Never paste your actual API key or token in test messages or screenshots. Always keep credentials secure in Coupler.io's header field.

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 — 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