API Errors & Status Codes

HTTP status codes

Code	Meaning
`200 OK`	Request succeeded
`201 Created`	Document or resource created successfully
`400 Bad Request`	Invalid request body or parameters
`401 Unauthorized`	Missing or invalid API key
`403 Forbidden`	API key valid, but insufficient permissions
`404 Not Found`	Document or resource does not exist
`409 Conflict`	Action not valid for current document state
`422 Unprocessable Entity`	Request understood but invalid (e.g., HTML too large)
`429 Too Many Requests`	Rate limit or quota exceeded
`500 Internal Server Error`	ZipZign error — contact support

Error response format

All errors return a JSON body:

{
  "error": "ErrorCode",
  "message": "Human-readable description of the error"
}

Common error codes

Authentication errors

{ "error": "Unauthorized", "message": "Invalid or missing API key" }

Validation errors

{ "error": "ValidationError", "message": "'signers' is required for type 'signable'" }

{ "error": "HTMLTooLarge", "message": "HTML content exceeds 500 KB limit" }

{ "error": "TooManySigners", "message": "Maximum 6 signers allowed per document" }

State conflict errors

{ "error": "DocumentAlreadySigned", "message": "Cannot modify content after signing has begun" }

{ "error": "ConsentRequired", "message": "consentGiven must be true to proceed with signing" }

Quota and rate limit errors

{
  "error": "QuotaExceeded",
  "message": "Monthly document quota reached. Upgrade your plan or wait for quota reset."
}

{
  "error": "RateLimitExceeded",
  "message": "Too many requests. Retry after 60 seconds.",
  "retryAfter": 60
}

Not found

{ "error": "NotFound", "message": "Document doc_abc123 not found" }

Handling errors in code

const response = await fetch('https://zipzign.com/api/documents', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!response.ok) {
  const err = await response.json();
  console.error(`ZipZign error [${response.status}]: ${err.error} — ${err.message}`);
  
  if (response.status === 429) {
    const retryAfter = err.retryAfter ?? 60;
    // back off and retry
  }
}

Updated on: 16/04/2026

Was this article helpful?

Thank you!