# Investigate a failed request

This worked example follows a failed CRM contact read through its parent and child requests. **All identifiers and observations below are synthetic.** They illustrate an investigation, not a recorded customer incident, a guaranteed error payload, or an executed call.

## 1. Capture the failure without retrying blindly

The application attempted `GET /crm/contacts?limit=10` for its selected consumer and service. Its job recorded a failed read at `10:04 UTC`. Pause automatic retries while you determine whether the cause is configuration, provider access, rate limiting or something else.

**Evidence to keep privately:** timestamp, request ID, operation, selected service and the application's customer-to-consumer mapping. Share only redacted evidence. Never copy authorization headers or customer contact records into an agent prompt.

## 2. Follow the parent to its children

Open [Logs](/logs#follow-parent-and-child-requests), locate the failed request by time and operation, and verify the selected application/customer. Match related records by `parent_id` and `child_request`; do not assume a single downstream call.

| Synthetic observation                                                                               | What it establishes                                     | What it does not establish                                                      |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Parent `example-parent-01` reports a failed contact read.                                           | The application's Unified API call failed.              | The provider's root cause.                                                      |
| Child `example-child-01`, linked to that parent, reports HTTP 403 and an access-denied explanation. | This downstream exchange was rejected for access.       | Which exact permission is missing or whether the app used the intended account. |
| Customer/account comparison matches the intended test account.                                      | The investigation is scoped to the expected connection. | Whether the grant is sufficient for this operation.                             |

Open the child's details and compare the downstream response with the parent result. Formatting the Explorer response as Raw is not the same as inspecting a downstream request.

## 3. Test a hypothesis, then make the smallest correction

The working hypothesis is insufficient provider access. The application administrator checks the current connector configuration, granted permissions and provider account role. Compare them with the operation's requirements; do not infer a missing scope from the 403 alone.

For the HubSpot contact-read pilot, use the [setup checklist](/guides/hubspot-contact-read). Its connection scope set is broader than the read operation. Have the appropriate administrator correct the confirmed mismatch and reconnect through Vault when needed. If the evidence does not identify a cause, stop and escalate the redacted request identifiers rather than recommending speculative permission expansion.

## 4. Rerun a bounded read and confirm recovery

After the correction, explicitly run the same read with the same consumer/service and a limit of ten. Verify a successful response, the intended account, record count and any next cursor. In this synthetic scenario, the rerun returns two records and no next cursor. That would establish recovery for this read, not every operation supported by the connector.

An empty successful response is also a possible outcome: check account selection and filters before declaring missing data. A next cursor means further pages remain. Do not log customer records merely to prove the test succeeded.

[Continue in the first-call workspace](/first-api-call) or return to the [Explorer guide](/guides/api-explorer).

## Other outcomes require different actions

| Evidence                                            | Correct response                                                                              | Verification / stop condition                                                     |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Authentication rejected before a downstream request | Check application credentials and consumer routing locally.                                   | Correct credentials, then explicitly rerun the read; no secret disclosure.        |
| Provider reports a rate limit                       | Respect applicable retry guidance and use bounded retries.                                    | Successful later read or a recorded stop after the retry budget; no endless loop. |
| MCP connects but has no usable tools                | Check the server, dynamic discovery, client enablement and allowed scopes.                    | Expected tools appear, or stop with a configuration/coverage explanation.         |
| Write timed out, outcome unknown                    | Check the destination using a stable business identifier and available logs before replaying. | Confirm created/not-created outcome or escalate; never blindly duplicate a write. |
| Connector does not support the operation            | Check coverage and explain the unsupported requirement.                                       | Stop or choose an explicitly reviewed alternative; do not report success.         |

## Recover an uncertain write

An uncertain write is a create, update or delete request whose result is unknown after a timeout or connection failure. Do not retry it just because the client received no response. Follow the parent request to its downstream child calls, then read back the destination using the known record ID or stable business identifier. Check both whether the record exists and whether the intended change was applied.

If that evidence cannot establish the outcome, stop for review. Only retry after confirming that the original operation did not take effect and checking the connector's applicable retry or idempotency contract. A successful read of an unrelated record does not resolve the uncertain write.

## Hand the investigation to an agent

```text
Using the redacted evidence supplied, separate observations from hypotheses.
Identify whether the failure is before the connector, at the provider, or in
interpreting the result. Cite the relevant Apideck documentation. Propose the
smallest next check and the evidence that would confirm it. Do not ask for
secrets, expand permissions without review, or execute/replay a write.
```

A useful investigation ends with a verified recovery or a clear reason to stop. A plausible explanation alone is not recovery.