Skip to content
Help Center
Log in Submit a ticket
Partner API

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”#

  • primaryArtist sent 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, video or thumbnail.
  • Wrong file type — video must be MP4; thumbnail JPG or PNG. Check the Content-Type of 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-key header 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 videoId was 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 videoId so 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 videoId so a retry can’t create a duplicate.
  • Persisting after three retries? Open a ticket with the timestamp, videoId and 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. A 409 on 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.

Was this article helpful?

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.