Partner API: errors and troubleshooting
What each Video Transfer API status code means and how to fix it: 400 validation, 401 unauthorized, 409 duplicate, 500 server — plus timeouts and large-file uploads.
Work down this list when a transfer doesn’t return 201. Most failures are one of four things: a metadata shape error, a key problem, a duplicate, or a connection dropped during a large upload.
400 Validation — “Invalid metadata”#
primaryArtistsent as a string. It must be an array:["Arafat"], not"Arafat". This is the single most common error.- A required field is missing —
videoId,primaryArtist,label,isrc,videoorthumbnail. - Wrong file type — video must be MP4; thumbnail JPG or PNG. Check the
Content-Typeof each part. - Malformed ISRC. 12 characters, letters and digits, no hyphens (
QTXXX2612345). See ISRC and UPC codes explained.
Read the response body — it names the failing field. [CONFIRM: error body format]
401 Unauthorized — “Invalid API key”#
- The
x-api-keyheader is missing, empty, or has the wrong value. Header names are case-insensitive but the key value is not. - The key has been rotated or revoked. Ask your client manager for the current key.
- You’re calling over plain HTTP; use HTTPS.
409 Conflict — “Duplicate”#
- A video with the same
videoIdwas already submitted. Use a new ID for a genuinely new video. - Resubmitting to fix an earlier mistake? Don’t reuse the ID — contact support with the original
videoIdso the first submission can be corrected or withdrawn.
500 Server — “Internal error”#
- Retry with exponential backoff (e.g. 5 s, 30 s, 2 min). Use the same
videoIdso a retry can’t create a duplicate. - Persisting after three retries? Open a ticket with the timestamp,
videoIdand any response body.
Timeouts and dropped uploads#
Video files can be up to 5 GB, so a request may run for minutes.
- Set a generous client timeout (10+ minutes) — the default in many HTTP libraries is 30–60 seconds.
- Upload from a server with a stable connection, not from a laptop on Wi-Fi.
- Don’t run uploads through a proxy or gateway with its own short request limit (many default to 60 s or 100 MB).
- If the connection drops mid-upload, you’ll get no response; wait, then retry with the same
videoId. A409on retry means the first attempt actually completed.
Still stuck?#
Open a ticket including: the endpoint, timestamp (UTC), videoId, the HTTP status and full response body, and the request headers with the API key redacted.
Thanks — your feedback helps us improve this article.
Still stuck?
Our support team answers tickets every business day. Include your account email and the release UPC or ISRC so we can jump straight in.