Skip to main content
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.
{
  "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.
{
  "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.
{
  "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.
{
  "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 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
}
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
}
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
}
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"
}
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:
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.
{
  "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 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 envelopeFix: 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.
{
  "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.
{
  "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.
{
  "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.
{
  "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.