ConverterHQDevelopers
Documentation

Errors

Stable machine-readable errors with retry guidance and request IDs.

Errors use a stable Problem Details envelope plus a ConverterHQ error code. Applications should branch on code, not human text.

Problem Details

Problem Details
{
  "type": "https://converterhq.io/developers/errors/file-password-protected",
  "title": "Password protected file",
  "status": 422,
  "code": "FILE_PASSWORD_PROTECTED",
  "retryable": false,
  "request_id": "req_..."
}

Retryability

Only transient/infrastructure errors should be blindly retried. Deterministic input errors require changing the request or file. Check the response's retryable flag, Retry-After when present and the error family before applying a generic retry policy.

Recovery strategy

Authentication and scope errors require a credential change; validation errors require a request change; protected/corrupt inputs require a file or setting change. Transient infrastructure failures can be retried with idempotency and bounded exponential backoff. A failed Job remains inspectable, so do not discard its diagnostics before deciding what to replay.

Request IDs

Keep the X-Request-ID response header. It links the request, Job, Task attempts and webhook diagnostics.