Troubleshooting failed upload requests

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

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.