API Error Codes

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:

PDF is password protected

Cause: The uploaded PDF is password protected and cannot be processed.Fix: Remove the password protection from the PDF before uploading.

{
  "type": "PDFIsPasswordProtected",
  "title": "PDF is password protected",
  "status": 400
}

Conversion failed

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.

{
  "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"
}

Broken download URL

Cause: The URL provided for file download is broken, expired, or inaccessible.Fix: Verify the URL is valid and publicly accessible, then retry.

{
  "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."
}

Page limit reached

Cause: The uploaded document exceeds the maximum page count allowed for processing.Fix: Split the document into smaller parts and process each separately.

{
  "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"
}

Cannot delete all pages

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.

{
  "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"
}

Page index out of bounds

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.

{
  "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"
}

PDF is not valid

Cause: The uploaded file is not a valid PDF.Fix: Ensure the file is a well-formed PDF before uploading.

{
  "type": "PDFIsNotValid",
  "title": "PDF is not valid",
  "status": 400
}

Watermark format is not supported

Cause: The watermark format provided in the request is not supported.Fix: Refer to the endpoint documentation for the list of supported watermark formats.

{
  "type": "WatermarkFormatIsNotSupported",
  "title": "Provided watermark format is not supported",
  "status": 400
}

OCR failed

Cause: OCR processing could not be completed on the provided file.Fix: Ensure the file is a valid PDF or image and retry.

{
  "type": "OCRFailed",
  "title": "OCR processing failed. Ensure the file is a valid, PDF or image.",
  "status": 400
}

Form parsing error

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.

{
  "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"
}

Client disconnected

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.

{
  "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 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:

Upload Exceeds maximum number of Documents for Envelope

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.

Resending Envelope for Signature

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:

File no longer available

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:

File too large

Cause: Attempting to upload a document that exceeds the file size limit.Fix: Ensure that uploaded files are no larger than 25 MB.

{
  "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:

File format not supported for document conversion

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 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).

File format not supported for envelope documents

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:

Too many documents

Cause: Attempting to add too many documents in an envelopeFix: Make sure your envelope is within the document limits allowed by the Nitro platform (15).

Invalid parameters

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.

{
  "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'}]"
}

Invalid platform method

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.

{
  "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']"
}

Invalid delivery instructions

Cause: The delivery instructions provided in the request are invalid.Fix: Check the extensions.errors array for specific validation failures in the delivery configuration.

{
  "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': {}}]"
}

Conversion not needed

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.

{
  "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.

{
  "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.

Guidelines

Tutorials and Guides

Troubleshooting

Developer Tools

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

405 - Method Not Allowed

406 - Not Acceptable

408 - Request Timeout

409 - Conflict

410 - Gone

413 - Content too large

415 - Unsupported Media Type

422 - Unprocessable Entity

429 - Too Many Requests

500 - Internal Server Error

​400 - Bad Request

​401 - Unauthorized

​403 - Forbidden

​404 - Not Found

​405 - Method Not Allowed

​406 - Not Acceptable

​408 - Request Timeout

​409 - Conflict

​410 - Gone

​413 - Content too large

​415 - Unsupported Media Type

​422 - Unprocessable Entity

​429 - Too Many Requests

​500 - Internal Server Error

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

405 - Method Not Allowed

406 - Not Acceptable

408 - Request Timeout

409 - Conflict

410 - Gone

413 - Content too large

415 - Unsupported Media Type

422 - Unprocessable Entity

429 - Too Many Requests

500 - Internal Server Error