When a call fails, the API returns a numeric code and a message. The message usually tells you exactly what to fix — always read the entire response body.
Overview of return codes
| Code | What it means | What to do |
|---|---|---|
200 |
OK — the request succeeded. | |
400 |
Error in the input data. | The specific cause is in the message, see below. |
401 |
Invalid or missing API key. | Check the x-api-key header, the key's validity (expiration), and that it belongs to the correct workspace. |
402 |
Insufficient credits. | Top up credits in the workspace. |
403 |
The workspace does not have API integration enabled. | The Signi API module is not active — contact sales@signi.com. |
404 |
Not found — the document or contact does not exist. | Check the ID — and that it belongs to your key's workspace. |
406 |
The operation cannot be performed in the document's current state. | See Document lifecycle — e.g. downloading a signed PDF is only possible in the completed state. |
410 |
The used version of the document template has been deleted. | Check which template and version you are calling. |
500 |
Error on Signi's side. | Try again; if it repeats, write to help@signi.com. |
What an error response looks like
Simple errors return only a message, e.g. a wrong key (401):
{ "message": "No valid token found" }
Structured errors also carry a code and a translation key:
{
"code": 400,
"errorCode": "Signi.Exceptions.PublicApi.ContractBadRequestException",
"translationKey": "public_api.bad_request…",
"message": "…what is wrong…"
}
Typical messages for a 400 error
“Invalid JSON” / “Invalid or missing json request provided”
- There is a typo in the JSON instructions — a JSON validator can help.
- Or the file is not encoded in UTF-8, or it is missing from the request entirely.
“Contract must have at least one proposer.”
peoplemust contain at least one person with"is_proposer": true— the author of the document (there can be more than one proposer).
“Contract role [role] is not enabled for this workspace”
- The signer role used (e.g. signing with a certificate) is not enabled in your workspace. Check the workspace settings, or contact support.
“Function [function] cannot be used for contract role [role]”
- The combination of role and function does not make sense — check
contract_rolefor the people in the JSON.
“Webhook is invalid” / “Webhook state [state] is not allowed”
- The webhook address is not valid, or you are reporting a state the webhook does not support. Supported states:
pending,completed,rejected,expired.
The signer is not in the workspace
- A signer's email with a Signi account must be assigned to the workspace that the API key belongs to — see the note in the Quickstart.
Where to go next
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article