Troubleshooting failed upload requests

Diagnosing an upload request step by step

When an upload request fails, work through these steps in order rather than jumping straight to a list of possible causes.

Step 1: Confirm the request is an upload request

Check that the failing request is actually going to an upload endpoint, such as /image/upload, /video/upload, or /raw/upload, or that you're calling an SDK upload method such as cloudinary.uploader.upload(), rather than a delivery URL or an Admin API call. At this stage, the upload hasn't completed yet, so delivery-side details, such as a delivery URL or public_id, aren't relevant until the upload itself succeeds. The diagnostics below apply to upload requests.

Step 2: Verify the upload configuration

Before looking at the specific error, confirm:

• Your server-side SDK uses the correct cloud name, API key, and API secret
• Whether you're sending a signed or unsigned upload, and, for unsigned uploads, that the request includes a valid, unsigned-enabled upload_preset
• You set the file parameter, which can be a file path, remote URL, or Data URI, correctly for your use case

Step 3: Capture the full error response

If the configuration looks correct, capture the complete error response rather than relying on the generic HTTP status alone. Most SDKs return more detail than a generic UnexpectedResponse or Error message. Look for:

• The HTTP status code
• error.message
• error.http_code
• error.name
• error.response, if available

Step 4: Match the error to a known cause

Use the full error details from Step 3 to narrow down the cause, as described in the sections below.

X-Cld-Error from failed API upload requests

• Check the X-Cld-Error message in the response header

• Using the response from the X-Cld-Error helps point in the correct direction to resolve the issue. For example, if the error message indicates that the cloud_name wasn't found, then double-check the configuration.

Extracting error messages from unsigned upload requests

When making unsigned upload requests via REST APIs or HTTP clients (such as OutSystems, Postman, or custom scripts), the actual error details from Cloudinary may not be immediately visible in the HTTP status message. To diagnose unsigned upload failures:

In HTTP response headers:

1. Look for the X-Cld-Error header in the HTTP response
2. This header contains the detailed error message from Cloudinary, such as:
   • Missing or invalid upload_preset
   • Unsupported parameters in unsigned uploads
   • Invalid multipart field structure
   • Cloud name configuration issues

In HTTP response body:

If the X-Cld-Error header isn't present, check the JSON response body for an error.message field:

Example: Diagnosing a 400 Bad Request

If you receive a 400 Bad Request error without a clear message:

1. Verify multipart field mapping: Ensure your request includes:

   • file: The binary file data (required)
   • upload_preset: The unsigned preset name (required for unsigned uploads)
   • Any other allowed unsigned parameters (optional)

2. Check the X-Cld-Error header: Extract and review the error message to identify the specific issue

3. Verify preset configuration: Confirm that the upload preset:

   • Exists in your Cloudinary account
   • Is configured for unsigned uploads

OutSystems-specific note:

When uploading from OutSystems using REST connectors or HTTP clients:

• Set the REST request method to POST
• Configure the request as multipart/form-data
• Send the file data in a multipart form field named file
• Include the upload_preset value as a multipart form field

Troubleshooting HTTP 401 errors from the Upload API

A 401 response from an upload request means Cloudinary rejected the request's credentials or signature before it could process the upload. Check each of the following:

• Invalid API key or API secret
• Credentials that belong to a different cloud than the one in the request
• A signed upload sent without a valid signature
• A disabled Cloudinary account

Troubleshooting HTTP 403 errors from the Upload API

A 403 response from an upload request means the credentials were valid, but the request itself was disallowed. Check each of the following:

• Upload restrictions configured on the account or product environment
• An unsigned upload sent to a preset that isn't enabled for unsigned uploads
• A restricted or disabled upload preset

Troubleshooting "Resource is invalid" and "Unsupported source URL" errors

These errors indicate that Cloudinary couldn't process the value passed in the file parameter. Check the following, particularly for Base64-encoded and Data URI uploads:

• The file parameter uses a format Cloudinary supports: a file path, a remote URL that's publicly reachable, or a correctly formatted Data URI
• The Data URI is well-formed, for example data:image/svg+xml;base64,<payload>, with no missing commas or truncated segments
• The Base64 payload itself is complete and valid, with no missing padding or characters lost in transit
• The MIME type in the Data URI matches the actual file content, for example image/svg+xml for an SVG
• For SVG uploads specifically, that the decoded content is valid XML
• You encode the request body correctly for the transport you use, for example, that a Base64 string embedded in JSON hasn't been double-encoded or had characters stripped

Failed Upload Widget request error message

When uploading via the Cloudinary Upload Widget, the widget returns an error message if the upload process fails. In most cases, this provides enough information to understand the root cause of the error and how to resolve it, similar to the X-Cld-Error message returned from API requests. If there are any errors during the upload process, the error message appears on the top-left hand side of the Upload Widget opposite an exclamation mark, indicating an unsuccessful request.

Most common causes for errors

Configuration issues

Any issues with the Cloudinary configuration setup for both the API and the Upload Widget results in Upload errors.

Account limits

Every account is subject to limitations, depending on the account plan and setup. Here is a full list of the account limitations for each plan.

Contact support

If the error message is too vague, or you are unfamiliar with the error and how to proceed, please contact our support team and provide details of the upload request and the error message you received.