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

# Troubleshooting Workflows

> Common troubleshooting workflows, tips, and escalation guidance for resolving Journey execution failures.

## Determining if a Failure is Global or Isolated

Before diving into individual error codes, first determine the scope of the failure — this significantly narrows down the likely cause.

1. Switch the toggle to **Total Users** in the Journey analytics view.
2. Analyse the ratio:
   * If **100% of users** are failing at a node → likely an Authentication or Mapping error.
   * If only a **small percentage** (e.g., 5%) are failing → likely a Consent or Bad Request (data quality) issue.

## Check Journey Trace Logs First

Always begin by reviewing the Journey Trace logs for the specific execution. The logs include the raw error response from the destination, which often contains additional context beyond the error code.

## Validate Destination Credentials Regularly

`AUTHENTICATION_ERROR` is one of the most common failure reasons. Set up periodic credential rotation reminders and ensure your Journey configurations are updated whenever tokens or API keys are refreshed via **Settings > Connections**.

## Test Payload Structure Before Production

`BAD_REQUEST` and `EVENT_PARSING_FAILED` errors typically originate from schema mismatches. Always validate your event payload against the destination's API schema in a staging environment before deploying to production.

## Tips & Warnings

<Warning>
  **Automatic Retries** — The system handles retries automatically for `SERVER_ERROR` and `SERVICE_UNAVAILABLE`. Do **not** manually re-inject profiles until the external service is confirmed stable. Premature re-injection can result in duplicate events being delivered once the service recovers.
</Warning>

<Tip>
  **Primary Identifier Mapping** — Always ensure your Primary Identifier (e.g., `external_id` or `email`) is mapped correctly and is never null. 90% of `BAD_REQUEST` errors are caused by a null value in the primary ID field. Validate this mapping first before investigating other causes.
</Tip>

## Getting Help

If you encounter an error not listed in this guide, or if the issue persists after following the recommended actions, contact the Support Engineering team.

**Email:** [support@zeotap.com](mailto:support@zeotap.com)

When contacting support, include the following for faster resolution:

* Journey execution ID
* Error code and timestamp
* Destination name and type
* Request ID from the Execution Details panel
* Steps already taken to resolve the issue