Custom API Troubleshooting
Messages never include your API's responses, record IDs, cursors or credentials, only what went wrong. "Nothing has been saved" means the setup dialog didn't save anything.
Setup messages
These appear in the setup or edit dialog.
Connecting to your API
| Message | Cause | Fix |
|---|---|---|
| Unable to connect | The API answered 401, or 403 without rate-limit headers, or an OAuth token endpoint refused the client or refresh token (HTTP 400). Also shown for settings the API can't be called with | Check the authentication type, the key or token, and for OAuth the token URL, client ID, secret, grant and refresh token |
| The API answered with an error (HTTP …) | The API returned another error status | Check Records Endpoint Path, the fixed parameters (some APIs require one, like fields) and the page size |
| The API's pagination or address didn't work as configured | A response broke the settings: no records array at Response Array Path; a next-page link to another address; a has-more or end flag that isn't true/false or contradicts the response; a repeated next position; a detail response with a different ID, or with more than one record; or an OAuth token response naming a different API host | Check the paths and the pagination style against a real response from your API |
| The API redirected the request, which is not allowed | The API answered with a redirect | Enter the address it redirects to, often a different host or https:// |
| The API's response couldn't be read. | The response wasn't JSON, or a token response had no usable access token | Check the endpoint returns JSON |
| The API couldn't be reached. | Network failure, a timeout, or a private or reserved address | Check the API address is public and online |
| Too many requests. | Your organization used its 30 setup actions this minute, or your API answered with its own rate limit (HTTP 429, or a 403 with rate-limit headers) | Wait the time shown |
| Your setup session expired. | The 30-minute test session ended | Enter the credentials again |
Records and mapping
| Message | Cause | Fix |
|---|---|---|
| Check the highlighted fields. | A field is missing or invalid, like a path that isn't a dot path, a detail path without {id}, or a page-size parameter missing for page or offset pagination | Fix the highlighted fields |
| N records have no ID. | Records in the list have no value at Record ID | Choose a field every record has |
| N records repeat an ID. | Two records in the list share a Record ID | Choose a field that is unique |
| A sampled record wasn't found at the detail path. | The detail request returned 404, an empty array, or 204 | Check Detail Path, and that {id} is filled by the right field |
| The API didn't return a detail record for the sample. | Fetching the sample's details took too long | Try again |
| The mapping does not work with the sample records. | A mapping check failed (see Discover Fields) | Fix the fields the dialog lists |
| This source already tracks N documents; the limit can't be lower. | The new limit is below the documents the source keeps | Enter at least that number, or delete documents first |
| The connection identity can't change. | An edit tried to change a field that identifies the source | Connect a new source instead |
Starting and saving
| Message | Cause | Fix |
|---|---|---|
| Insufficient credits | Not enough credits for the new documents (20 each) | Add credits from Open Billing |
| This source changed since you opened it. | Someone saved the source while you were editing | The dialog reloads the latest version; nothing was started |
| Another sync of this source just started. | Two people pressed Start at once, or a scheduled step began first | Nothing; the dialog reloads and shows View Sync |
| This source is still importing. Wait for it to finish. | The previous part's documents are still being processed | Wait, then try again |
| This source is paused. Resume it to scan for records. | The source is paused | Resume it, then try again |
| This project is archived | The source's project was archived | Restore the project |
| The vector store is not configured. / The vector store needs an update. | The project's vector store isn't set up, or needs the update that lets documents be replaced in place | Open vector store settings |
| An embedding message | The project's embedding model isn't set up | Open embedding settings |
| A storage, Terms or business details message | Syncing is paused for the whole organization | See Paused syncing |
| We couldn't confirm the result. | The connection dropped before the app answered; the change may or may not have been saved | Use Check status, or reopen the source |
| Your session has expired. | You were signed out | Sign in again |
| You don't have permission to manage sources. | Only Owners and Admins can set up custom API sources | Ask an Owner or Admin |
Scheduled check problems
These happen after the first Start, when the app reads your API on its own. See When a scheduled check fails for what each one does.
Each problem shows on the source row and in its Monitor dialog: the waiting causes as Waiting to retry, reconnect_required as Reconnect required, protocol_error, redirect_refused, missing_ids and duplicate_ids as Protocol error, and the rest that stop the source as Scan stopped. The dialog gives the reason in plain words.
| Cause | Code | What happens | Fix |
|---|---|---|---|
Your API's rate limit (HTTP 429, or a 403 that carries a Retry-After header, or an X-RateLimit-Remaining or RateLimit-Remaining of 0) | rate_limited | Waits as long as the API asks (1 minute if it doesn't say), then retries | Nothing. If it keeps happening, use a smaller page size or a longer interval |
| Not enough credits | insufficient_credits | Waits 1 hour, then retries | Add credits |
| Vector store or embedding not ready | target_unavailable | Waits 1 hour, then retries | Fix the project's settings |
| Credentials refused (HTTP 401, a 403 without rate-limit headers, or an OAuth refresh refused) | reconnect_required | Stops | Enter new credentials in Edit Custom API |
| Pagination broken | protocol_error | Stops | Check the pagination settings against the API |
| Redirect | redirect_refused | Stops | Use the address it redirects to (a new source, since the API address can't change) |
| Records without IDs | missing_ids | Stops; nothing from that step is added | Fix the records in your API |
| Repeated IDs in one step | duplicate_ids | Stops; nothing from that step is added | Fix the records in your API, or check the list isn't returning the same page twice |
| Settings no longer valid | invalid_config | Stops | Edit the source, or connect a new one |
| List refused from its start (HTTP 400 or 410 on the first page) | list_rejected | Stops | Check the fixed parameters and the endpoint |
| Pass longer than 100,000 pages | cycle_too_long | Stops | Use conditions your API applies (fixed parameters) or a larger page size |
| Saved position expired (HTTP 400 or 410 when continuing) | position_expired | Restarts the pass once; stops on a second expiry | Usually nothing. If it repeats, shorten the time between steps |
| Network errors, other HTTP errors, unreadable responses, a refreshed token that couldn't be saved | network_error, http_error, invalid_response, token_not_saved, scan_failed | Retries after 5, 15, 60, 60 minutes; stops on the fifth in a row | Check the API is up |
A record whose detail can't be fetched or built (a 404, an unreadable response, empty text) doesn't stop the source: that document shows an error in Documents, and the next pass retries it once.
Rate limits answered with 403
Some APIs (GitHub, for one) answer a rate limit with HTTP 403 instead of 429. The connector treats a 403 as a rate limit, and waits, when the answer carries:
- a
Retry-Afterheader, in seconds or as an HTTP date; or X-RateLimit-Remaining: 0orRateLimit-Remaining: 0.
The wait comes from Retry-After, then X-RateLimit-Reset (a time), then RateLimit-Reset (seconds), and is 1 minute if none is given; it's always between 1 second and 1 hour. A 403 with none of these headers, like a 401, means the credentials were refused: the source stops with reconnect required.
Clearing a stopped source
Fix the cause first, then choose Check Now in the source's Monitor dialog (Owners and Admins). For Reconnect required, save new credentials in Edit Custom API first. After cycle_too_long or a second expired position, Check Now starts a new pass from the beginning. See Check Now.