Troubleshooting
Start with the failing step: inspecting a source, building a definition, executing an API, reading a saved run, or purchasing credit. Save its non-secret identifier and error before changing anything. Each step has a different recovery path.
On this page
Inspection or build does not produce a usable API#
Confirm the URL points to the collection you need. A product listing, individual product page, and search results page can expose different records and fields. Prefer a stable public collection URL without session tokens or private parameters.
Review the selected records and required fields before building. A preview is not a validated API, and a build still in progress is not ready for integration. If the proposed output does not match your use case, revise the collection or field selection. See choosing a source and fields and schemas.
The request is rejected#
Check the generated contract and response body together:
| Symptom | Next step |
|---|---|
| Authentication failure | Check that the server sends the expected bearer key and that it has not expired or been revoked. |
| Access denied or source unavailable | Confirm the selected workspace, source identifier, and credential scope. |
| Input validation error | Compare field names, types, content type, and limits with the saved input schema. |
| Definition conflict | Review the active definition and schema before updating expected_version. |
| Rate or capacity limit | Honor any retry delay and reduce concurrency. Do not increase budgets automatically. |
| Insufficient credit | Inspect Billing and the purchase state before attempting another execution. |
Do not remove authentication, version checks, or limits to make a rejected request pass. The error guide covers HTTP statuses and retry boundaries.
A request times out#
A connection timeout does not tell you whether execution started or completed. Check the existing run when an identifier is available. Review its outcome, retained result, and charging information before resubmitting.
The source run endpoint requires an Idempotency-Key. Preserve the same key and unchanged request to recover a settled result. Do not generate a new key merely because the first response was lost: a new key represents a new execution.
A delivery_identity_conflict means the key was reused with a changed request. An unsettled request can return result_already_running_or_failed; respect its retry delay and inspect the run. Retry read-only checks with bounded backoff and follow idempotency for the complete recovery rules.
Records are missing or incomplete#
Read the summary alongside the records. Check page and detail limits, within_scope_passed, and catalog_complete where present. A one-page run may have satisfied its budget while leaving most of a collection untouched.
Missing detail fields can reflect disabled enrichment, incomplete enrichment, or absent source values. Compare with the saved schema and source examples. Preserve missing values; do not replace a missing price with zero or an execution failure with an empty dataset.
If the source has changed, follow source changes. Review a new definition before changing your application configuration.
Run details or credit are unavailable#
For a run link, sign in to the correct workspace and refresh. Expired or unretained results cannot be recovered by refreshing; metadata may still help diagnose the run.
For a payment, inspect purchase history and settlement status. A return from checkout is not confirmation that credit has been added. Avoid repeating an uncertain payment and follow billing.
If the issue persists, send the minimal reproduction and identifiers described in contact support.