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
internal_error	500	Something went wrong on our end

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);
  }
}