Troubleshoot from durable facts rather than retrying blindly. ConverterHQ exposes a request ID, resource state, Task attempt history and delivery records specifically so failures can be diagnosed after the original HTTP connection is gone.
Start with the request
- Record HTTP status and
X-Request-ID. - Parse the Problem Details
codeandretryablefields. - Check whether the request returned or created a File, Job or Task ID.
- Respect
Retry-Afterbefore retrying a throttled request.
Inspect durable execution
For asynchronous work, retrieve the Job and inspect each Task and attempt. A queued Task points toward concurrency/capacity; a running Task with no recent progress points toward execution; a failed Task should carry a stable error code and diagnostic context. Do not treat a client timeout as a Job failure.
Conversion failures
First verify the detected/input format, requested output format and pair-specific settings against the capability endpoint. Password-protected, corrupt, truncated or unsupported inputs are deterministic failures and should not be placed in an infinite retry loop. Transient engine or infrastructure failures can be retried according to the returned guidance.
Webhook delivery
Verify the raw request body before parsing it, accept duplicate event delivery idempotently, return a 2xx only after the event is durably accepted, and use the delivery console to inspect response status, latency, next retry and replay history.
Build a support bundle
For escalation, include environment, timestamp, X-Request-ID, Job/File/Task IDs, endpoint and HTTP method, SDK name/version, error code, and a redacted request shape. Never send API keys, cloud credentials, signed URLs or unredacted customer files in a support ticket.