Errors and their solutions (API)

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

What an error response looks like

Simple errors return just 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…"
}

In addition, the response may also carry the technical fields error and link.

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 will help.
• Or the file is not in UTF-8 encoding, or is missing from the request entirely.

„Contract must have at least one proposer."

• people must contain at least one person with "is_proposer": true — the document's author (there can be more than one proposer).

„Contract role [role] is not enabled for this workspace"

• The used signer role (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_role for 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 cannot handle. Supported states: pending, completed, rejected, expired.

The signer is not in the workspace

• A signer's email with an account in Signi must be assigned to the workspace that the API key belongs to — see the note in the Quickstart.

Where to go next

• Quickstart — your first document for signing via the API
• Full overview of calls and responses