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

# Common API Issues

> Typical API errors, their causes, and how to resolve them.

## Authentication

Symptoms:

* 401 responses
* token appears valid but request fails

Checks:

* verify Authorization header format: `Bearer <token>`
* confirm token is not expired
* confirm route group matches token scope

Resolution:

* issue a fresh token
* retry request with explicit auth header
* validate environment base URL and route prefix

## Validation Errors

Symptoms:

* 400 responses for payload shape
* missing required fields

Checks:

* validate required fields for endpoint
* validate enum values and case-sensitive strings where applicable
* validate date and timezone formats

Resolution:

* start from a known-good minimal payload
* add fields incrementally until desired shape is reached
* keep payload examples versioned by client SDK or integration source

## Event Delays

Symptoms:

* event accepted but not visible in canonical list

Checks:

* inspect Incoming Events status first
* check process\_error and retryable
* confirm event\_id linkage for processed items

Resolution:

* if failed terminal, fix payload and resend
* if processing, continue polling within expected window
* validate idempotency strategy to avoid duplicate logical submissions

## Campaign Send Issues

Symptoms:

* campaign launch fails
* campaign remains scheduled unexpectedly
* recipients remain queued or fail in batches

Checks:

* sender domain verification
* provider configuration present
* audience mode and snapshot validity
* scheduled\_for value relative to current time

Resolution:

* correct prerequisites and relaunch
* test with a smaller audience
* monitor recipient-level outcomes for first successful run

## Workflow Delivery Gaps

Symptoms:

* expected workflow email not delivered
* execution marked skipped

Checks:

* contact has valid email
* contact is subscribed
* workflow default template exists
* queue item status and process\_error fields

Resolution:

* fix contact eligibility
* fix template or provider config
* retrigger with a controlled test event

## Next Content Step

Attach API Reference links beside each issue so users can jump to schema-level details quickly.