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:

The route receives application/json as exact bytes before any JSON middleware.
The endpoint uses the signing secret for the same environment—not an API key.
The process clock is synchronized and within the 300-second tolerance.
The signed input is exactly <Chia-Webhook-Timestamp>.<raw_body> with no newline or reserialization.
The receiver accepts only the current secret plus, during rotation, one retiring secret.
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 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.