# 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.

## 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](/docs/choosing-a-source/) and [fields and schemas](/docs/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](/docs/errors/) 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](/docs/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](/docs/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](/docs/billing/).

If the issue persists, send the minimal reproduction and identifiers described in [contact support](/docs/support/).