Errors

All API errors return a consistent JSON structure:

{
  "error": {
    "type": "not_found",
    "message": "Signature request not found."
  }
}

Validation errors include a details array:

{
  "error": {
    "type": "invalid_request",
    "message": "Validation failed.",
    "details": [
      "Signers can't be blank",
      "File must be a PDF"
    ]
  }
}

HTTP status codes

Status	Description
200	Success
201	Created
204	No Content (successful deletion)
400	Bad Request — missing or malformed parameters
401	Unauthorized — invalid or missing API key
403	Forbidden — insufficient permissions
404	Not Found — resource doesn’t exist
422	Unprocessable Entity — validation failed
429	Too Many Requests — rate limit exceeded
500	Internal Server Error

Error types

Type	Status	Description
invalid_request	400	Required parameter missing or malformed
unauthorized	401	API key is missing, invalid, revoked, or expired
forbidden	403	API key doesn’t have permission for this action
not_found	404	The requested resource was not found
validation_error	422	One or more fields failed validation
rate_limited	429	Too many requests — back off and retry (see below)
internal_error	500	Something went wrong on our end

Common error messages

403 Forbidden

Message	Cause
”Owner email must be verified to use the API”	The organization owner has not verified their email address. Verify your email in the VisiSign dashboard before making API calls.
”Active subscription required to use the API”	The organization does not have an active subscription. Subscribe to a plan in Settings > Billing.
”API key doesn’t have permission for this action”	The API key is missing the required scope for this endpoint.

429 Too Many Requests

Message	Cause
”Hourly send limit reached. Try again later.”	You’ve exceeded the hourly envelope send limit (50/hr). Wait and retry.
”Daily send limit reached. Upgrade your plan for unlimited sends.”	You’ve exceeded the daily send limit for your plan.
”Too many signing requests sent to {email} in the last hour”	More than 5 signing requests sent to the same recipient within an hour.
”API quota exceeded. Upgrade your plan for more API calls.”	Monthly API call quota exceeded for your plan.

See Rate Limits for full details on thresholds.

Handling errors

Check the HTTP status code first, then inspect the error.type for programmatic handling:

const response = await fetch("https://api.visisign.app/v1/signature_requests", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

if (!response.ok) {
  const { error } = await response.json();

  switch (error.type) {
    case "unauthorized":
      // Re-authenticate or check API key
      break;
    case "not_found":
      // Resource doesn't exist
      break;
    case "validation_error":
      // Check error.details for specific field errors
      console.error(error.details);
      break;
    default:
      console.error(error.message);
  }
}