> ## Documentation Index
> Fetch the complete documentation index at: https://developers.gonitro.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# API Error Codes
> Common Nitro API error responses (400, 401, 404, 500…) explained, with what causes each and how to resolve them.
When interacting with the Nitro APIs, you might encounter various HTTP error responses. Here's a breakdown of the most common error codes and how to resolve them.
## 400 - Bad Request
This error occurs when the request is malformed or contains invalid parameters.
**Common causes:**
* Missing required fields
* Invalid query syntax
* Sending data in the wrong format
**How to fix:**
* Double-check your request body or query parameters to ensure all fields are correctly structured.
**Nitro-specific causes:**
**Cause:** The uploaded PDF is password protected and cannot be processed.
**Fix:** Remove the password protection from the PDF before uploading.
```json theme={null}
{
"type": "PDFIsPasswordProtected",
"title": "PDF is password protected",
"status": 400
}
```
**Cause:** The file or files could not be converted to the target format.
**Fix:** Ensure the input file is a valid, non-corrupted file of the expected type.
```json theme={null}
{
"type": "ConversionFailed",
"title": "Conversion Failed",
"status": 400,
"extensions": {
"from_type": "docx",
"to_type": "pdf"
},
"detail": "The file or files could not be converted to pdf, please ensure the input file or files are of type docx"
}
```
**Cause:** The URL provided for file download is broken, expired, or inaccessible.
**Fix:** Verify the URL is valid and publicly accessible, then retry.
```json theme={null}
{
"type": "BrokenDownloadURL",
"title": "Broken Download URL",
"status": 400,
"extensions": {
"url_truncated": "https://example.com/...file.pdf?token=abc"
},
"detail": "The URL 'https://example.com/...file.pdf?token=abc' (truncated) is broken or expired (non 200 response), or inaccessible. Please check the URL and try again."
}
```
**Cause:** The uploaded document exceeds the maximum page count allowed for processing.
**Fix:** Split the document into smaller parts and process each separately.
```json theme={null}
{
"type": "PageLimitReached",
"title": "Page Limit Reached",
"status": 400,
"extensions": {
"page_count": 120,
"page_limit": 100
},
"detail": "Page limit reached page-count: 120, page-limit: 100"
}
```
**Cause:** The delete-pages request would remove every page of the document (for example, deleting the only page of a single-page document). A PDF must keep at least one page.
**Fix:** Remove at least one page index from the request so the resulting document is not empty.
```json theme={null}
{
"type": "CannotDeleteAllPages",
"title": "Cannot Delete All Pages",
"status": 400,
"extensions": {
"page_count": 1
},
"detail": "Deleting the requested pages would remove all 1 pages of the document"
}
```
**Cause:** The request references one or more page indices that do not exist in the document (page indices are zero-based). Applies to operations that accept page indices, such as rotate, split, delete-pages, extract-text, watermark and ocr.
**Fix:** Only send page indices between 0 and the document's page count minus one. The `extensions` object lists the offending indices and the document's page count.
```json theme={null}
{
"type": "PageIndexOutOfBounds",
"title": "Page Index Out Of Bounds",
"status": 400,
"extensions": {
"page_indices": [5, 6, 7],
"page_count": 2
},
"detail": "Page indices out of bounds: [5, 6, 7], document page-count: 2"
}
```
**Cause:** The uploaded file is not a valid PDF.
**Fix:** Ensure the file is a well-formed PDF before uploading.
```json theme={null}
{
"type": "PDFIsNotValid",
"title": "PDF is not valid",
"status": 400
}
```
**Cause:** The watermark format provided in the request is not supported.
**Fix:** Refer to the endpoint documentation for the list of supported watermark formats.
```json theme={null}
{
"type": "WatermarkFormatIsNotSupported",
"title": "Provided watermark format is not supported",
"status": 400
}
```
**Cause:** OCR processing could not be completed on the provided file.
**Fix:** Ensure the file is a valid PDF or image and retry.
```json theme={null}
{
"type": "OCRFailed",
"title": "OCR processing failed. Ensure the file is a valid, PDF or image.",
"status": 400
}
```
**Cause:** A form part in the multipart request could not be parsed.
**Fix:** Ensure each part of the multipart request uses the correct content type.
```json theme={null}
{
"type": "FormParsingError",
"title": "Form Parsing Error",
"status": 400,
"extensions": {
"part": "params",
"mime_type": "application/json"
},
"detail": "Error parsing form part: params, please ensure content is of type: application/json"
}
```
**Cause:** The client disconnected before the request could be completed.
**Fix:** Ensure your client maintains the connection for the duration of the request, especially for large files or slow networks.
```json theme={null}
{
"type": "ClientDisconnectedError",
"title": "The client disconnected before the request could be completed",
"status": 400
}
```
***
## 401 - Unauthorized
This error means your request lacks valid authentication credentials.
**Common causes:**
* Attempting a request with a missing or expired token
* Attempting a request with an access token in the wrong format.
**How to Fix:**
* Verify that your access token is included and valid.
* Check out the [Authentication and Authorization](https://developers.gonitro.com/docs/authentication/credentials) guide if you need go through the process of obtaining credentials and tokens.
***
## 403 - Forbidden
This error means the server understood the request and the credentials, but the caller isn't allowed to access the resource.
**Common causes:**
* The provided `nitro-guest-id` is invalid or has expired.
* The authenticated user doesn't have permission to access the requested resource.
**How to fix:**
* Verify that the `nitro-guest-id` header is present, well-formed, and not expired.
* Confirm that the authenticated account has access to the endpoint or resource.
***
## 404 - Not Found
This indicates that the requested resource doesn't exist.
**Common causes:**
* Attempting to get or modify a resources that does not exist. For example, trying to add a Document to an Envelope that doesn't exist.
**How to Fix:**
* Check that you're calling the correct endpoint and using valid resource identifiers.
***
## 405 - Method Not Allowed
This error means that the resource exists, but it does not accept the HTTP method you used.
**Common causes:**
* Using the wrong HTTP method for the endpoint.
* For example, sending a GET request to an endpoint that only supports POST.
**How to fix:**
* Check the API reference to confirm which methods are supported for the endpoint, and update your request.
***
## 406 - Not Acceptable
This error occurs when the server cannot produce a response in a format acceptable to your client.
**Common causes:**
* The Accept header specifies a content type the API doesn't support.
* Missing or incorrect Accept header in the request.
**How to fix:**
* Check the response content type in the API reference tab for the endpoint, and update your Accept header to match, or remove it to use the default.
***
## 408 - Request Timeout
The server timed out before the request could be completed.
**Common causes:**
* Network problems such as high latency, slow connections, or firewalls can generate a server timeout.
* Large payloads (for example, document uploads) that take longer than the allowed processing time.
**How to Fix:**
* Check your network connection and retry later
***
## 409 - Conflict
The request could not be completed because of a conflict with the current state of the target resource. The conflict must be resolved before retrying.
**Nitro-specific causes:**
**Cause**: Uploading a Document to an Envelope that already contains the maximum of 15 Documents.
**Fix**: Remove unused Documents from the Envelope or combine smaller files into a single Document before retrying.
**Cause**: Attempting to send for signature an Envelope that has already been delivered and is in sent status.
**Fix**: For sending Envelopes, verify the current status and ensure you are not resending an Envelope that has already been delivered.
***
## 410 - Gone
This error indicates that the requested resource is no longer available.
**Nitro-specific causes:**
**Cause:** Attempting to retrieve a job result file after it has expired or been removed from temporary storage.
**Fix:** Re-submit the original request to regenerate the file.
***
## 413 - Content too large
This error indicates that the request was valid, but the payload exceeded the maximum size allowed by the system.
**Nitro-specific causes:**
**Cause:** Attempting to upload a document that exceeds the file size limit.
**Fix:** Ensure that uploaded files are no larger than 25 MB.
```json theme={null}
{
"type": "FileTooLarge",
"title": "File Too Large",
"status": 413,
"extensions": {
"file_size_mb": 42.5,
"file_size_limit_mb": 25.0
},
"detail": "File too large file-size(MB): 42.5, limit(MB): 25.0"
}
```
***
## 415 - Unsupported Media Type
This error indicates that the file format or media type sent in the request is not supported by the system.
**Nitro-specific causes:**
**Cause:** Attempting to upload a document with an unsupported file format to the `/sign/conversions` endpoint.
**Fix:** Ensure that uploaded files are in one of the supported formats.
* Refer to the [Convert File to PDF](https://developers.gonitro.com/docs/api-reference/sign/convert-file-to-pdf) endpoint documentation for the complete list of supported file formats.
* Include the **type** parameter in the form data matching the file's MIME type (e.g., **application/xml** for .xml files).
**Cause:** Attempting to upload a non-PDF document to the `/sign/envelopes/{envelopeID}/documents` endpoint.
**Fix:** This endpoint only accepts PDF files. Convert your document to PDF format before uploading, or use the /sign/conversions endpoint to convert supported formats to PDF first.
***
## 422 - Unprocessable Entity
This error means the request was well-formed but contains semantic issues the server can't process.
**Nitro-specific causes:**
**Cause:** Attempting to add too many documents in an envelope
**Fix:** Make sure your envelope is within the document limits allowed by the Nitro platform (15).
**Cause:** The parameters provided for the operation are invalid.
**Fix:** Check the `extensions.errors` array for the specific fields and validation errors, then correct your request.
```json theme={null}
{
"type": "InvalidParamsError",
"title": "Invalid Parameters",
"status": 422,
"extensions": {
"errors": [
{
"field": "page",
"error": "Input should be a valid integer",
"input": "abc"
}
]
},
"detail": "Invalid parameters: [{'field': 'page', 'error': 'Input should be a valid integer', 'input': 'abc'}]"
}
```
**Cause:** The `method` value provided is not valid for the endpoint group.
**Fix:** Use one of the allowed methods listed in `extensions.allowed_methods` for the given endpoint group.
```json theme={null}
{
"type": "InvalidPlatformMethodError",
"title": "Invalid Platform Method",
"status": 422,
"extensions": {
"method": "convert",
"allowed_methods": [
"rotate",
"redact"
],
"group": "transformations"
},
"detail": "Invalid method: convert, allowed methods for group transformations: ['rotate', 'redact']"
}
```
**Cause:** The delivery instructions provided in the request are invalid.
**Fix:** Check the `extensions.errors` array for specific validation failures in the delivery configuration.
```json theme={null}
{
"type": "InvalidDeliveryError",
"title": "Invalid Delivery Instructions",
"status": 422,
"extensions": {
"errors": [
{
"field": "type",
"error": "Field required",
"input": {}
}
]
},
"detail": "Invalid delivery instructions: [{'field': 'type', 'error': 'Field required', 'input': {}}]"
}
```
**Cause:** The input file is already in the target format — no conversion is required.
**Fix:** Skip the conversion step if the file is already in the desired format.
```json theme={null}
{
"type": "ConversionNotNeededError",
"title": "Conversion Not Needed",
"status": 422,
"extensions": {
"mime_type": "application/pdf"
},
"detail": "Input content type matches target type: application/pdf"
}
```
***
## 429 - Too Many Requests
This error indicates that you have exceeded the allowed request rate for the API.
**Common causes:**
* Sending too many requests in a short period of time.
**How to fix:**
* Wait the number of seconds indicated in `extensions.retry_after` before retrying, ideally using exponential backoff.
* Reduce the request rate where possible.
```json theme={null}
{
"type": "RateLimitExceeded",
"title": "Rate limit exceeded",
"status": 429,
"extensions": {
"retry_after": 3.5
},
"detail": "Rate limit exceeded; retry after 3.5 seconds."
}
```
***
## 500 - Internal Server Error
A generic error indicating something went wrong on our end.
**Common causes:**
* Server failure
* Unhandled exception in processing
**How to fix:**
* Try your request again later. If the issue persists, contact support with details of your request and error response.