> ## Documentation Index
> Fetch the complete documentation index at: https://oneviewhub.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Conversion API Errors

> Diagnose and resolve common Conversion API errors in OneView to ensure accurate conversion tracking across all platforms.

# Error Codes

<Info>
  OneView classifies integration responses into normalized outcomes used by the pipeline controller. These determine retry, pausing, and acknowledgement behavior.
</Info>

## Skipped

Requests are marked as `SKIPPED` when OneView intentionally avoids sending a conversion to an ad platform to prevent errors or policy violations. These are non-failing outcomes by design.

Common reasons:

* Consent not granted for advertising: OneView records
  "Consent for using data for advertising purposes (ad\_storage) was not granted."
* Lookback window exceeded at the destination (Google Ads, X/Twitter, Microsoft Ads). OneView auto-skips to reduce destination-side error rates.

### Subcategories

* Consent not granted (ad\_storage): User did not grant advertising storage; request is intentionally skipped.
* Destination lookback exceeded — Google Ads Conversion Action: Event older than the action's click-through window; skipped to avoid destination rejection.
* Destination lookback exceeded — X/Twitter Web Event Tag: Event older than the tag's lookback window; skipped to avoid destination rejection.
* Destination lookback exceeded — Microsoft Ads Conversion Goal: Event older than the goal's window; skipped to avoid destination rejection.

<CodeGroup>
  ```text Example (Consent) theme={null}
  Consent for using data for advertising purposes (ad_storage) was not granted. You need to grant ad_storage to send Conversion API requests.
  ```

  ```text Example (Google Ads lookback) theme={null}
  Click-through event exceeded your Conversion Action lookback window of N days by M days.
  OneView automatically marks these conversions as SKIPPED to reduce the error rate on your Google Ads account.
  ```

  ```text Example (X/Twitter lookback) theme={null}
  Click-through event exceeded your Web Event Tag lookback window of N days by M days.
  OneView automatically marks these conversions as SKIPPED to reduce the error rate on your Twitter Ads account.
  ```

  ```text Example (Microsoft Ads lookback) theme={null}
  Click-through event exceeded your Conversion Goal lookback window of N minutes by D days.
  OneView automatically marks these conversions as SKIPPED to reduce the error rate on your Microsoft Ads account.
  ```
</CodeGroup>

<AccordionGroup>
  <Accordion title="How to fix">
    <Steps>
      <Step title="Grant required consent where applicable">
        Ensure `ad_storage` (and equivalent) is granted before sending events. Gate event forwarding on consent.
      </Step>

      <Step title="Align destination lookback windows">
        Adjust conversion action/tag/goal lookback windows to match your attribution strategy, or reduce conversion delays in your pipeline.
      </Step>

      <Step title="Validate freshness and deduplication">
        Confirm event timestamps are in UTC, delays are expected, and idempotency keys prevent late duplicates.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

<Note>
  Behavior: `SKIPPED` requests are acknowledged by the pipeline (no retry). They are recorded for observability and do not count as failures.
</Note>

## Fatal Error

`FATAL_ERROR` indicates a non-retryable problem that requires configuration changes. OneView will stop retrying.

Typical causes:

* Destination misconfiguration (e.g., webhook misconfigured, ad account misconfigured)
* Incompatible attribution/PII mode combinations. For example, Google Ads Conversion Action set to `EXTERNAL` while Enhanced Conversions (PII routing) is enabled
* Validation errors that the destination will never accept

### Subcategories

* KNOWN\_FATAL\_ERROR: Non-recoverable configuration issue detected; requires user action.
* CAPI\_WEBHOOK\_MISCONFIGURED: Webhook/event trigger configuration invalid for the workspace.
* AD\_ACCOUNT\_MISCONFIGURED: Destination account or credentials not set up/authorized correctly.
* FATAL\_ERROR: Integration reported a non-retryable error; retries are halted.

<Warning>
  Fatal errors are not retried. Fix the configuration and reprocess affected conversions if necessary.
</Warning>

<AccordionGroup>
  <Accordion title="How to fix">
    <Steps>
      <Step title="Review the error detail and reason">
        Check the error message and any provided `reason`/`solution` fields to identify the exact misconfiguration.
      </Step>

      <Step title="Fix destination configuration">
        Examples: choose a compatible attribution model for the conversion action, verify required scopes/credentials, and ensure the webhook is healthy and active.
      </Step>

      <Step title="Resend only after fixes">
        Once fixed, replay the affected conversions or allow the next eligible events to flow.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

<Warning>
  Behavior: Fatal conditions trigger a pause on the affected webhook in order to prevent repeated failures. The pipeline returns `KNOWN_FATAL_ERROR` and does not retry until configuration is fixed and the webhook is resumed.
</Warning>

## Transient Error

`TRANSIENT_ERROR` covers temporary failures such as network issues, brief API outages, and certain rate limits. OneView classifies these as retryable and will attempt again automatically with backoff.

Possible mappings in the pipeline include `KNOWN_TRANSIENT_ERROR` and `RATE_LIMIT_ERROR` handling.

<Info>
  No action is typically required. If transient errors persist for prolonged periods for a specific integration, review rate limits and batch sizes.
</Info>

### Subcategories

* KNOWN\_TRANSIENT\_ERROR: Temporary remote/system failure; the pipeline will retry.
* RATE\_LIMIT\_ERROR: Destination rate limiting encountered; will be retried with backoff.

<AccordionGroup>
  <Accordion title="How to fix">
    <Steps>
      <Step title="Monitor retries and final outcomes">
        Confirm that retries are succeeding within the platform’s SLO. Intermittent failures should resolve without intervention.
      </Step>

      <Step title="Reduce pressure if persistent">
        Stagger conversion uploads, lower concurrency, or spread traffic across regions if applicable.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

<Info>
  Behavior: Transient errors map to `KNOWN_TRANSIENT_ERROR` or `RATE_LIMIT_ERROR` and are retried automatically with backoff. Once a retry succeeds, the pipeline acknowledges the message.
</Info>