Troubleshooting
Placeholders not detected or places misaligned
Fix placeholders that SignatureAPI doesn't find and places that land in the wrong spot, with the error each problem returns and how to check a file first.
Places go wrong in two ways: SignatureAPI can’t match a place to its position, and the create request fails, or the request succeeds and a place shows up somewhere you didn’t expect. This page covers both.
Check the file first
Before you create an envelope, upload the file and call Retrieve upload structure. It lists every placeholder SignatureAPI finds, with its page and position, and an errors array for keys that are invalid or repeated. If a placeholder isn’t in that list, SignatureAPI can’t see it.
The same call returns the size of every page, in points, which you need for fixed positions.
The request fails
Each of these is a 422 response to the create request, so no envelope is created. The detail names the place or placeholder.
| Error | Cause | Fix |
|---|---|---|
invalid-places | A place has no matching [[key]] in the document and no fixed position. | Add the placeholder text, or give the place a fixed position. |
invalid-placeholder | The document has a [[key]] that no place uses. | Add a place with that key, or remove the text. |
duplicate-placeholder | The same placeholder appears twice. | Give each place its own key and placeholder. |
placeholder-position-conflict | A place has a fixed position and a matching placeholder. | Keep one of the two. |
mixed-placeholders | The document mixes legacy signature placeholders, such as [[client.signature]], with places. | Use places and [[place_key]] placeholders only. |
place-outside-page | A place sits partly or fully outside its page. | Move it inside the page. |
fixed-position-outside-document | A fixed position names a page the document doesn’t have. | Use a page number from 1 to the document’s page count. |
no-signing-place | A signer has no signature or initials place. | Add one with that signer’s recipient_key. |
SignatureAPI doesn’t find a placeholder
When a placeholder is in the file but missing from the upload structure, check these:
- The text must be real text. SignatureAPI reads the document’s text. A placeholder inside an image or a scanned page isn’t text. Try to select and copy it in a PDF reader: if you can’t, neither can SignatureAPI. Add it as text in the source file and export again.
- The key must be valid. A key has 1 to 32 characters: lowercase letters, digits and underscores, starting with a letter.
[[Client_Sign]]and[[client-sign]]are not valid keys;[[client_signs_here]]is. - Use double square brackets.
[[client_signs_here]]positions a place.{{client_signs_here}}is a template field in a DOCX and is replaced with data, not with a place. - The key must match exactly. The text between the brackets must equal the place’s
key, character for character.
A place lands in the wrong spot
Fixed positions measure to the bottom-left corner
top is the distance from the top edge of the page to the bottom-left corner of the place, not its top-left corner. A place positioned as if top pointed at its top edge sits one place-height too high. Add the place’s height to top to correct it.
Positions are in points
top and left are in points: 1 point is 1/72 inch, about 0.35 mm. Values in pixels or millimeters put the place in the wrong spot or off the page. A US Letter page is 612 × 792 points, and an A4 page is 595 × 842. See Points and page sizes.
Pages start at 1
page counts from 1, so "page": 2 is the second page. "page": 0 fails validation, and a page past the end of the document fails with fixed-position-outside-document.
The place is bigger or smaller than the placeholder
A placeholder sets where a place goes, not how big it is. A signature place is always 2.5 times as wide as its height, which is 20 to 60 points (60 by default), whatever the size of the placeholder text. If the signature covers nearby text, lower height or leave more room around the placeholder. See Signature.
The placeholder shows on the signed document
The rendered place covers the placeholder, but a colored placeholder can show around it. Set the placeholder text color to white in the source file so only the place remains. See Hide the placeholder.
Try positions before you send
On the Positioning page, drag a place over a Letter or A4 page, or a page sized from your own PDF, to read its top and left values. Then send a test envelope and open its ceremony to see the result on the real document. Test envelopes are free.
Related
- Positioning: placeholders and fixed positions.
- Use placeholders: a worked example.
- Troubleshooting templates: when the DOCX merge itself fails.