Troubleshooting Artwork Upload Failures (API Version 2.1)

Audience: Customer Support Agents (Tier 1 & Tier 2)

Related Products: Vistaprint Partner API, Mass-Customization Fulfillment

---

Overview

Partners routing orders through the Vistaprint API may experience artwork upload failures, particularly when using API Version 2.1. This is a known issue caused by system timeouts when processing unusually large print files or highly complex unflattened PDFs.

When a partner is escalated to you via the Nova voicebot regarding this issue, Nova will have already gathered the partner's API version and logged it in the Zendesk ticket notes.

Verification Steps

Before troubleshooting, verify that the partner is experiencing the known v2.1 timeout issue.

1. Review Ticket Notes: Check the Zendesk ticket created by Nova to confirm the partner stated they are using API version 2.1.

2. Confirm Error Codes: Ask the partner if their system is receiving a 408 Request Timeout or 504 Gateway Timeout error in their API response logs.

3. Determine File Size: Ask the partner for the approximate size and format of the file that is failing. (Files over 500MB are highly susceptible to this timeout on v2.1).

Resolution & Workarounds

If the partner is confirmed to be experiencing the v2.1 timeout issue, guide them through the following solutions:

1. Upgrade to the Latest API Version (Recommended)

Advise the partner to update their integration to API Version 3.0 (or the newest available stable release). The newer endpoints feature optimized payload handling and support for asynchronous uploads, which resolves the timeout constraints seen in version 2.1.

2. Optimize the Artwork File

If an immediate API upgrade is not possible for the partner's development team, ask them to optimize the file before pushing the payload:

• Ensure the file is saved as a strictly flattened PDF.

• Remove unnecessary layers, hidden elements, or embedded color profiles that bloat the file size.

• Keep the total file size under the recommended threshold of 300MB for synchronous API pushes.

3. Manual Upload via Partner Portal

As an emergency workaround for time-sensitive orders, the partner can manually upload the artwork directly through the Vistaprint Partner Portal UI.

Escalation Path

If the partner has upgraded their API, optimized their files, and is still experiencing upload failures, the issue must be escalated to the API Engineering team.

• Change the Zendesk ticket status to Open.

• Reassign the ticket to the Tier 2 - API Integration Support queue.

• Include the partner's API Key (do NOT paste the full key in the ticket, only the last 4 digits), the exact timestamp of the failed upload, and the specific error code received.