# Troubleshooting

Start with the HTTP status, error `code`, and validated `Chia-Request-Id` when present. An opaque edge failure may have no Chia ID; retain a partner-owned correlation ID and UTC time instead. Do not paste secrets, `Authorization`, full response bodies, webhook payloads, event/summary/catalog IDs, authenticated asset URLs, or handoff fragments into logs, tickets, chat, or AI tools.

## Fast diagnosis

| Symptom | Likely cause | Safe next action |
|---|---|---|
| `401 invalid_api_key` | Missing, revoked, malformed, or wrong-environment key | Check the origin and secret-manager binding; the SDK rejects prefix mismatches locally, while the API intentionally does not enumerate key environment |
| `403 insufficient_scope` | Runtime key used for finance or finance key used for catalog | Move the call to the correct isolated role |
| `304 Not Modified` | Catalog `ETag` still current | Keep the last valid unexpired publication; refresh its cache deadline |
| `404 catalog_asset_unavailable` | Stale/withdrawn asset, wrong role, or malformed asset request | Purge that candidate and refetch the catalog; do not probe variants |
| `409 idempotency_key_reused` | Same key, different webhook-test body | Generate one new UUIDv4 for the new logical test |
| `409 webhook_endpoint_unavailable` | Registered endpoint failed readiness or delivery prerequisites | Check exact DNS/TLS/path registration and receiver health |
| `429 rate_limit_exceeded` | Credential budget exhausted | Wait for `Retry-After`, add jitter, and reduce polling |
| `500` / `502` / `503` / `504` | Temporary origin or edge failure | Bounded exponential backoff; retain the last valid unexpired catalog |
| `unsupported_api_version` | Credential/release/config drift | Stop publication and compare the signed release/configuration |
| `invalid_response` | Body, origin, header, or schema failed closed validation | Stop publication and escalate with request ID |
| `asset_integrity_error` | Header, length, type, or digest mismatch | Abort the sink, purge bytes, alert, and refetch catalog |

## Webhook signature fails

Check in this order:

1. The route receives `application/json` as exact bytes before any JSON middleware.
2. The endpoint uses the signing secret for the same environment—not an API key.
3. The process clock is synchronized and within the 300-second tolerance.
4. The signed input is exactly `<Chia-Webhook-Timestamp>.<raw_body>` with no newline or reserialization.
5. The receiver accepts only the current secret plus, during rotation, one retiring secret.
6. `Chia-Webhook-Id`, `Chia-Webhook-Type`, and `Chia-Version` exactly match the verified envelope.

Use the public vectors in [`api/partner/examples/webhook-signature-test-vectors.json`](https://partners.chia.health/examples/webhook-signature-test-vectors.json) to isolate verifier bugs without a real secret.

## Webhook test is accepted but nothing arrives

`POST /v2/webhook_tests` returning `202` means the request was accepted, not delivered.

- Confirm the receiver URL registered for that exact environment.
- Confirm public DNS, trusted TLS, exact path, no redirect, and no query string.
- Confirm your ingress limit allows the documented small JSON body.
- Check receiver metrics by type/environment/status only; do not inspect or log raw production payloads.
- Repeating the identical API request with the same durable idempotency key only replays its original `202` acceptance result. It does **not** enqueue or force another webhook delivery.
- Chia continues the original synthetic delivery's normal retry schedule for up to 24 hours after a transport failure or non-`2xx`. After repairing the receiver, either wait for that retry or create an immediate new logical test with a new UUIDv4 idempotency key. A new key creates a new signed test event; never reuse the old key with a different body. Live business activation requires a separately reviewed durable outbox/queue redesign for the agreed 72-hour window; do not treat this synthetic path as that capability.

## Catalog disappears

This is usually a safe failure, not a reason to loosen validation. Check publication expiry, a `catalog.updated` invalidation, local service-state freshness, asset integrity, care-origin mismatch, and current legal/configuration state. Hide an invalid/inactive card. Never keep an expired card or synthesize terms from an older version.

## Handoff opens generic Chia

Generic Chia is the required fail-closed outcome for a neutral choice or missing, invalid, expired, superseded, withdrawn, or revoked publication context. Do not infer or repair attribution from browser history, a cookie, app focus, return timing, or a partner identifier.

## Latency, redirects, and throttling

- A mobile view or tap must not wait on the Partner API. If it does, move catalog/asset work back to the scheduled partner cache and local snapshot.
- Treat every `3xx` from the JSON or asset origins as a protocol/security failure. Do not follow it or add a new host to an allowlist from a response.
- On `429`, honor a valid `Retry-After`, apply jitter, coalesce refreshes, and inspect polling frequency. Do not retry per user.
- On transient `5xx`/timeouts, preserve only the last valid unexpired snapshot and retry within the bounded operational budget.
- Alert when origin p95 exceeds 500 ms or origin p99 exceeds one second. The hourly authenticated CI canary must fail above three seconds, and scheduled-workflow failures must be routed to the named incident channel before launch. These are provisional infrastructure guardrails—not achieved production SLA evidence—until deployment, load/failure testing, and the parties' G-11 service-level approval are complete.

## Escalation packet

Send the named Chia integration support contact from the signed onboarding receipt:

- environment and credential **role** (never the credential or full prefix);
- UTC timestamp and partner-owned random correlation ID;
- operation name, HTTP status, error code, retryable flag, and validated `Chia-Request-Id` when present;
- expected versus observed behavior in non-sensitive terms;
- SDK version and contract digest from `PARTNER_CONTRACTS`.

If credentials, raw webhooks, handoff URLs, or consumer-health data may have leaked, use the contractual incident channel immediately instead of ordinary support.