Google documents that Data Manager API enum values can grow. A closed switch statement can throw, discard diagnostics, mark a failed batch successful, or retry a permanent error forever when a new `ErrorReason` appears.
Use this for WordPress lead uploads, WooCommerce conversions, CRM-qualified leads, agency connectors, scheduled batch workers, dashboards, and alerts that parse Data Manager API responses.
Quick answer
Treat unknown reason strings as first-class evidence. Store the raw reason, request ID, destination, count, status, timestamps, safe metadata, code version, and a redacted batch reference. Set the operational state to `needs_classification`, do not invent row attribution, and apply only transport-level retry rules that are independently known to be safe. Alert an owner and add a fixture after classification.
What to check first
- Find every enum, switch, serializer, database constraint, dashboard filter, alert rule, and retry branch that assumes the current reason list is complete.
- Create fixtures for a known retryable reason, known permanent reason, empty reason, malformed response, and synthetic future value such as `FUTURE_POLICY_SIGNAL`.
- Preserve request ID, destination, terminal status, reason, count, safe metadata, first seen, last seen, attempts, library version, and source batch reference.
- Keep unknown aggregate reasons at destination and count level unless the response or controlled batch design proves an exact failed row.
- Route unknowns to a bounded alert with deduplication, an owner, runbook link, and review deadline while protecting customer identifiers.
Diagnostic table
Use this table to keep the work practical. It connects the symptom to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Inventory closed reason assumptions | Find every enum, switch, serializer, database constraint, dashboard filter, alert rule, and retry branch that assumes the current reason list is complete. | Synthetic future values survive parsing, storage, dashboards, exports, and alerts. |
| Preserve unknown raw values | Create fixtures for a known retryable reason, known permanent reason, empty reason, malformed response, and synthetic future value such as `FUTURE_POLICY_SIGNAL`. | The worker stops or retries only according to an explicit safe policy. |
| Use a neutral classification state | Preserve request ID, destination, terminal status, reason, count, safe metadata, first seen, last seen, attempts, library version, and source batch reference. | Operators can find the request, destination, count, version, and redacted source batch. |
| Alert one named owner | Keep unknown aggregate reasons at destination and count level unless the response or controlled batch design proves an exact failed row. | A later mapping can reclassify historical records without losing the original reason. |
Why this usually happens
- Generated clients and validation schemas can lag the service.
- Database enum constraints reject values before logs are written.
- Default branches often confuse unknown with success or retryable.
- Asynchronous status can provide aggregate reasons without row detail.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
switch (reason) {
case 'FORMAT_INVALID': return permanent(reason);
case 'DESTINATION_TEMPORARILY_UNAVAILABLE': return retry(reason);
default: return { state: 'needs_classification', rawReason: reason, retry: false };
}
// Persist request ID, destination, count, timestamps, and redacted batch reference.
Safe fix order
Do the work in a sequence that makes each result easy to prove. Stop if a step produces new evidence that changes the incident scope.
- Inventory closed reason assumptions
- Preserve unknown raw values
- Use a neutral classification state
- Alert one named owner
- Add tests after documented classification
Decision rule
Pass when a future reason is stored and surfaced without crashing, silent success, endless retry, invented row attribution, or personal-data leakage.
What to tell the client or owner
Give the owner the affected versions, exact workflow, observed result, business impact, evidence location, temporary control, named owner, and next review time. Remove credentials and personal data from shared screenshots and logs.
Production verification checklist
- Synthetic future values survive parsing, storage, dashboards, exports, and alerts.
- The worker stops or retries only according to an explicit safe policy.
- Operators can find the request, destination, count, version, and redacted source batch.
- A later mapping can reclassify historical records without losing the original reason.
Mistakes to avoid
- Do not change several plugins, cache rules, or infrastructure settings before preserving a baseline.
- Do not treat one successful test as proof for retries, alternate clients, background work, or mixed-version fleets.
- Do not paste secrets, personal data, complete production payloads, or customer files into tickets or screenshots.
- Do not close the test until the final user-visible state and the server-side evidence agree.
Questions teams ask during testing
Should every unknown reason be retried?
No. Unknown does not mean temporary. Use only retry signals documented independently, apply limits, and require classification.
Can the system map an aggregate unknown reason to one lead?
Not unless the response or your isolated batch design proves it. Preserve the aggregate count honestly.
When HandL WP should help
Bring in HandL WP when a production checkout, form, email, media pipeline, code-quality gate, or paid lead workflow is at risk. We can preserve evidence, isolate the failing layer, make the smallest corrective change, and verify the result across WordPress, connected services, logs, and the user journey.
If this is active on a production site, make Data Manager API errors diagnosable.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references