Updated on 2026-10-19 10:06:21. Version: 3.3.0

Author: ndbroadbent

.openapi-generator/FILES

@@ -28,6 +28,7 @@ docs/CustomFile.md
 docs/ErrorOrMultipleErrorsResponse.md
 docs/ErrorResponse.md
 docs/Folder.md
+docs/ForbiddenErrorResponse.md
 docs/JsonSchema.md
 docs/ListSubmissionsResponse.md
 docs/MoveFolderData.md
@@ -93,6 +94,7 @@ docspring/models/custom_file.py
 docspring/models/error_or_multiple_errors_response.py
 docspring/models/error_response.py
 docspring/models/folder.py
+docspring/models/forbidden_error_response.py
 docspring/models/json_schema.py
 docspring/models/list_submissions_response.py
 docspring/models/move_folder_data.py
@@ -160,6 +162,7 @@ test/test_custom_file.py
 test/test_error_or_multiple_errors_response.py
 test/test_error_response.py
 test/test_folder.py
+test/test_forbidden_error_response.py
 test/test_json_schema.py
 test/test_list_submissions_response.py
 test/test_move_folder_data.py

CHANGELOG.md

@@ -1,3 +1,14 @@
+### 3.3.0 [October 18, 2026]
+
+- Submissions and combined submissions can be in the new `insufficient_credits` state: a live PDF that your credit
+  balance can't cover is saved and processed once you add credits. See
+  https://docspring.com/docs/api-guide/credits-and-rate-limits/.
+- generate_pdf, batch_generate_pdfs and combine_pdfs document the 402 response for insufficient credits. Their
+  responses can include a `code`, which is `insufficient_credits` on a 402.
+- generate_pdf, batch_generate_pdfs, create_pdf_template, create_pdf_template_from_upload, create_html_template and
+  copy_template document a 403 response with a `code` of `upgrade_required` (the plan doesn't include it) or
+  `account_suspended`.
+
 ### 3.2.0 [October 18, 2026]
 
 - Response models keep fields this version doesn't know in `additional_properties`.

README.md

@@ -6,7 +6,7 @@ templates with your data, generates PDFs from HTML templates, combines PDFs and
 [Documentation](https://docspring.com/docs/) · [API reference](https://docspring.com/docs/api/) ·
 [PyPI](https://pypi.org/project/docspring/) · [Changelog](https://github.com/DocSpring/docspring-python/blob/main/CHANGELOG.md)
 
-Version 3.2.0. Requires Python >=3.9.
+Version 3.3.0. Requires Python >=3.9.
 
 ## Install and configure
 

docs/BatchGeneratePdfs201Response.md

@@ -10,6 +10,7 @@ Name | Type | Description | Notes
 **errors** | **List[str]** |  | [optional] 
 **submission_batch** | [**SubmissionBatch**](SubmissionBatch.md) |  | 
 **submissions** | **List[object]** |  | 
+**code** | **str** | `insufficient_credits` when the response is a 402. | [optional] 
 
 ## Example
 

docs/Client.md

@@ -146,6 +146,10 @@ Generates up to 50 PDFs in a single request. Each submission can use a different
 and data. Supports both synchronous (wait for all PDFs) and asynchronous processing. More
 efficient than individual requests when creating multiple PDFs.
 
+Live PDFs use credits. If any live submission is waiting for credits, the API returns 402 and the
+others are still processed: check each submission's `state`. See
+[Credits & Rate Limits](https://docspring.com/docs/api-guide/credits-and-rate-limits/).
+
 See also:
 - [Batch Generate PDFs](https://docspring.com/docs/api-guide/generate-pdfs/batch-generate-pdfs/) - Request format, responses, and limits
 
@@ -221,6 +225,8 @@ Name | Type | Description  | Notes
 
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
+**402** | insufficient credits |  -  |
+**403** | account suspended |  -  |
 **201** | submissions created |  -  |
 **200** | some PDFs with invalid data |  -  |
 **401** | authentication failed |  -  |
@@ -238,6 +244,11 @@ Combines multiple PDFs from various sources into a single PDF file. Supports mer
 submission PDFs, template PDFs, custom files, other merged PDFs,
 and PDFs from URLs. Merges the PDFs in the order provided.
 
+Combining uses credits (4 per source PDF, plus 4 per unit of the combined PDF), even with a test API
+token or watermarked source PDFs. If your balance can't cover it, the API returns 402 and the combined
+submission waits in the `insufficient_credits` state until you add credits. See
+[Credits & Rate Limits](https://docspring.com/docs/api-guide/credits-and-rate-limits/).
+
 
 ### Example
 
@@ -308,9 +319,10 @@ Name | Type | Description  | Notes
 
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
+**402** | insufficient credits |  -  |
+**403** | test API token used to delete custom files |  -  |
 **201** | combined submission created |  -  |
 **422** | invalid request |  -  |
-**403** | test API token used to delete custom files |  -  |
 **400** | invalid JSON |  -  |
 **401** | authentication failed |  -  |
 
@@ -398,6 +410,7 @@ Name | Type | Description  | Notes
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
 **200** | copy template success |  -  |
+**403** | the plan's template limit is reached |  -  |
 **404** | folder not found |  -  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
@@ -830,6 +843,7 @@ Name | Type | Description  | Notes
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
 **201** | returns a created template |  -  |
+**403** | the plan's template limit is reached |  -  |
 **401** | authentication failed |  -  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
@@ -921,6 +935,7 @@ Name | Type | Description  | Notes
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
 **201** | returns a pending template |  -  |
+**403** | the plan's template limit is reached |  -  |
 **401** | authentication failed |  -  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
@@ -1006,6 +1021,7 @@ Name | Type | Description  | Notes
 |-------------|-------------|------------------|
 **201** | returns a pending template |  -  |
 **401** | authentication failed |  -  |
+**403** | the plan's template limit is reached |  -  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
 
@@ -1522,6 +1538,10 @@ Generate a PDF
 Creates a PDF submission by filling in a template with data. Supports both synchronous (default) and
 asynchronous processing. Add the `wait=false` query parameter to return immediately.
 
+Live PDFs use credits; test PDFs (`test: true`) are free and watermarked. If your balance can't cover a
+live PDF, the API returns 402 and the submission waits in the `insufficient_credits` state until you add
+credits. See [Credits & Rate Limits](https://docspring.com/docs/api-guide/credits-and-rate-limits/).
+
 See also:
 - [Customize the PDF Title and Filename](https://docspring.com/docs/api-guide/generate-pdfs/customize-pdf-title-and-filename/) - Set custom metadata
 - [Handling Truncated Text](https://docspring.com/docs/api-guide/generate-pdfs/handle-truncated-text/) - Handle text that doesn't fit in fields
@@ -1600,8 +1620,10 @@ Name | Type | Description  | Notes
 
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
+**402** | insufficient credits |  -  |
 **201** | submission created |  -  |
 **422** | invalid request |  -  |
+**403** | live data requests need Starter or higher |  -  |
 **401** | authentication failed |  -  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
@@ -1699,6 +1721,9 @@ Retrieves the details and status of a combined submission. Returns processing st
 download URL (if processed), metadata, and information about any integrated actions
 (e.g., S3 uploads).
 
+`insufficient_credits` means the combined submission is waiting for credits and is processed once you
+add them. If it's still waiting after 30 days, it moves to `error`.
+
 
 ### Example
 
@@ -2038,6 +2063,9 @@ Retrieves the details and status of a PDF submission. Returns processing state,
 URL (if processed), metadata, submission data (optional), and information about any
 integrated actions. Use this to poll for completion when using asynchronous processing.
 
+`insufficient_credits` means the submission is waiting for credits and is processed once you add them.
+If it's still waiting after 30 days, it moves to `error`.
+
 
 ### Example
 
@@ -2124,6 +2152,9 @@ Retrieves the status and results of a batch PDF generation job. Returns processi
 completion statistics, and optionally includes all individual submission details. Use this
 to poll for completion when using asynchronous batch processing.
 
+Submissions waiting for credits are in the `insufficient_credits` state and count as pending, so the
+batch stays `pending` until you add credits or they stop waiting after 30 days.
+
 
 ### Example
 

docs/CombinePdfsData.md

@@ -10,7 +10,7 @@ Name | Type | Description | Notes
 **metadata** | **object** |  | [optional] 
 **password** | **str** |  | [optional] 
 **source_pdfs** | **List[object]** |  | 
-**test** | **bool** | Deprecated, and has no effect. A combined PDF is a test or live document because of its source PDFs. | [optional] 
+**test** | **bool** | Deprecated, and has no effect. Combining always uses credits, even with a test API token or watermarked source PDFs. | [optional] 
 
 ## Example
 

docs/CreateCombinedSubmissionResponse.md

@@ -7,7 +7,9 @@ Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
 **status** | **str** |  | 
 **combined_submission** | [**CombinedSubmission**](CombinedSubmission.md) |  | 
+**error** | **str** |  | [optional] 
 **errors** | **List[str]** |  | [optional] 
+**code** | **str** | `insufficient_credits` when the response is a 402. | [optional] 
 
 ## Example
 

docs/CreateCustomFileResponse.md

@@ -7,6 +7,7 @@ Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
 **status** | **str** |  | 
 **custom_file** | [**CustomFile**](CustomFile.md) |  | 
+**error** | **str** |  | [optional] 
 **errors** | **List[str]** |  | [optional] 
 
 ## Example

docs/CreatePdfSubmissionData.md

@@ -12,7 +12,7 @@ Name | Type | Description | Notes
 **field_overrides** | **object** |  | [optional] 
 **metadata** | **object** |  | [optional] 
 **password** | **str** |  | [optional] 
-**test** | **bool** |  | [optional] 
+**test** | **bool** | Generate a watermarked test PDF. Test PDFs are free; live PDFs (the default) use credits. | [optional] 
 **version** | **str** |  | [optional] 
 
 ## Example

docs/CreateSubmissionDataRequestEventResponse.md

@@ -7,6 +7,7 @@ Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
 **status** | **str** |  | 
 **event** | [**SubmissionDataRequestEvent**](SubmissionDataRequestEvent.md) |  | 
+**error** | **str** |  | [optional] 
 **errors** | **List[str]** |  | [optional] 
 
 ## Example