ConverterHQDevelopers
Documentation

Troubleshooting production integrations

A deterministic runbook for request failures, stuck Jobs, conversion errors, webhook delivery and support escalation.

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

  1. Record HTTP status and X-Request-ID.
  2. Parse the Problem Details code and retryable fields.
  3. Check whether the request returned or created a File, Job or Task ID.
  4. Respect Retry-After before 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.