Errors use a stable Problem Details envelope plus a ConverterHQ error code. Applications should branch on code, not human text.
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.