Why Signature Requests Fail
Updated 9/8/20262 min read
A Hoicko signature request most commonly fails due to (1) an expired or incorrect PFX certificate password, (2) a "Pdf Text" trigger phrase that doesn't exist in the target document, or (3) a malformed API call missing required token authentication. Check the Failed stat card and Analytic table for the specific action and timestamp, then re-verify your profile's configuration.
Reading the Failure Data
Every signature profile dashboard shows a Failed counter alongside Success, and every individual attempt is logged in the Analytic table with:
- Document name (if available)
- Created By (the user or system that triggered it)
- Action Type (e.g., PDF_SIGN)
- Activity Time (exact timestamp, e.g., 17/07/2026 05:59 PM)
- API Status (SUCCESS or FAILED, color-coded)
- IP Address of the request origin
Common Causes of Failure and Fixes
| Cause | How to Identify | Fix |
|---|---|---|
| Wrong/expired File Password | Consistent failures across all documents in a profile | Re-enter the correct password or re-upload a renewed PFX file |
| "Pdf Text" not found in document | Failures only on specific document templates | Update the Pdf Text trigger to match the actual document wording, or switch to "Select Area" |
| Expired PFX certificate | Failures start suddenly after a working period | Request a renewed certificate from your CA and re-upload |
| Malformed API/cURL request | Failures logged with unusual IP addresses or missing document names | Re-copy the cURL command via COPY CURL and verify the token is included correctly |
Step-by-Step: Diagnosing a Failure
- Open the affected signature profile's dashboard.
- Check the Failed stat card to confirm the scope of the issue.
- Scroll to the Analytic table and locate the failed row by Activity Time.
- Cross-reference the IP Address — internal IPs suggest a manual or internal system issue; external IPs suggest a third-party integration problem.
- Adjust the profile configuration (password, Pdf Text, or PFX file) and re-attempt.
Frequently Asked Questions
Where can I see the exact reason a signature failed, not just that it failed?
The Analytic table's API Status column flags FAILED rows; for deeper diagnostics, check with your integration logs or Hoicko support using the Activity Time and IP Address as reference points.
Do failed attempts count against my monthly PDF sign limit?
This depends on your Hoicko plan — check with your account admin, but failed attempts are tracked separately from successful sends in the "This Month" breakdown.
Can I retry a failed signature without re-uploading the PFX file?
Yes, if the PFX file itself is valid — simply resend the document. Only re-upload the PFX if the certificate itself was the cause of failure.
Related content
Is this article helpful?
Help us improve our articles.