Uploading large files

View as Markdown

Send a large file, such as a long video or a whole project as a ZIP, straight to storage. Then use it in an edit, a render or a ZIP import.

Smaller files can go straight into an edit, whose request can be up to 64 MB. Files up to 100 MB take one PUT. Larger files, up to 8 GB, go up in parts.

Run the steps in order, in one shell or one file: each step reuses what the one before it set. BLITFRAME and BLITFRAME_API_KEY are set as in the quickstart, and its Before you start lists what each language needs. In Go and Java, the later steps go inside main.

1. Create an upload

POST /v1/uploads with the file's name and exact size. The examples upload background.mp4 from the current folder.

UPLOAD=$(curl -s -X POST $BLITFRAME/uploads \
  -H "Authorization: Bearer $BLITFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"background.mp4","sizeBytes":'$(wc -c < background.mp4 | tr -d ' ')'}')
UPLOAD_ID=$(echo "$UPLOAD" | jq -r .id)
UPLOAD_URL=$(echo "$UPLOAD" | jq -r .url)
import os, requests

api = os.environ["BLITFRAME"]
headers = {"Authorization": f"Bearer {os.environ['BLITFRAME_API_KEY']}"}

upload = requests.post(f"{api}/uploads", headers=headers,
                       json={"fileName": "background.mp4", "sizeBytes": os.path.getsize("background.mp4")}).json()
upload_id = upload["id"]
upload_url = upload["url"]
import { readFile, stat } from "node:fs/promises";

const api = process.env.BLITFRAME;
const headers = { Authorization: `Bearer ${process.env.BLITFRAME_API_KEY}` };
const json = { ...headers, "Content-Type": "application/json" };

const upload = await (
  await fetch(`${api}/uploads`, {
    method: "POST",
    headers: json,
    body: JSON.stringify({ fileName: "background.mp4", sizeBytes: (await stat("background.mp4")).size }),
  })
).json();
const uploadId = upload.id;
const uploadUrl = upload.url;
<?php
function call(string $method, string $path, ?array $body = null, array $headers = []): array {
    $headers[] = "Authorization: Bearer " . getenv("BLITFRAME_API_KEY");
    $ch = curl_init(getenv("BLITFRAME") . $path);
    curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => $method]);
    if ($body !== null) {
        $headers[] = "Content-Type: application/json";
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    return json_decode(curl_exec($ch), true);
}

$upload = call("POST", "/uploads", ["fileName" => "background.mp4", "sizeBytes" => filesize("background.mp4")]);
$uploadId = $upload["id"];
$uploadUrl = $upload["url"];
require "net/http"
require "json"

def call(method, path, body = nil, headers = {})
  uri = URI(ENV["BLITFRAME"] + path)
  headers = { "Authorization" => "Bearer #{ENV["BLITFRAME_API_KEY"]}" }.merge(headers)
  headers["Content-Type"] = "application/json" if body
  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
    http.send_request(method, uri.request_uri, body&.to_json, headers)
  end
  JSON.parse(response.body)
end

upload = call("POST", "/uploads", { fileName: "background.mp4", sizeBytes: File.size("background.mp4") })
upload_id = upload["id"]
upload_url = upload["url"]
package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func call(method, path string, body any, headers map[string]string) map[string]any {
	var payload bytes.Buffer
	if body != nil {
		if err := json.NewEncoder(&payload).Encode(body); err != nil {
			panic(err)
		}
	}
	req, err := http.NewRequest(method, os.Getenv("BLITFRAME")+path, &payload)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BLITFRAME_API_KEY"))
	if body != nil {
		req.Header.Set("Content-Type", "application/json")
	}
	for name, value := range headers {
		req.Header.Set(name, value)
	}
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	var out map[string]any
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
	return out
}

func main() {
	file, err := os.Open("background.mp4")
	if err != nil {
		panic(err)
	}
	info, err := file.Stat()
	if err != nil {
		panic(err)
	}
	upload := call("POST", "/uploads", map[string]any{"fileName": "background.mp4", "sizeBytes": info.Size()}, nil)
	uploadID := upload["id"].(string)
	uploadURL, _ := upload["url"].(string)
	_, _ = uploadID, uploadURL // the next steps use them
}
using System.Net.Http.Json;
using System.Text.Json.Nodes;

var api = Environment.GetEnvironmentVariable("BLITFRAME");
var http = new HttpClient();

async Task<JsonNode> call(HttpMethod method, string path, object? body = null, params (string Name, string Value)[] headers)
{
    var request = new HttpRequestMessage(method, api + path);
    request.Headers.Authorization = new("Bearer", Environment.GetEnvironmentVariable("BLITFRAME_API_KEY"));
    if (body != null) request.Content = JsonContent.Create(body);
    foreach (var (name, value) in headers) request.Headers.Add(name, value);
    var response = await http.SendAsync(request);
    return (await response.Content.ReadFromJsonAsync<JsonNode>())!;
}

var upload = await call(HttpMethod.Post, "/uploads", new { fileName = "background.mp4", sizeBytes = new FileInfo("background.mp4").Length });
var uploadId = upload["id"]!.GetValue<string>();
var uploadUrl = (string?)upload["url"];
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;

public class Example {
    static final ObjectMapper json = new ObjectMapper();

    static JsonNode call(String method, String path, String body, String... headers) throws Exception {
        HttpRequest.Builder request = HttpRequest.newBuilder(URI.create(System.getenv("BLITFRAME") + path))
            .header("Authorization", "Bearer " + System.getenv("BLITFRAME_API_KEY"))
            .method(method, body == null ? HttpRequest.BodyPublishers.noBody() : HttpRequest.BodyPublishers.ofString(body));
        if (body != null) request.header("Content-Type", "application/json");
        if (headers.length > 0) request.headers(headers);
        HttpResponse<String> response = HttpClient.newHttpClient().send(request.build(), HttpResponse.BodyHandlers.ofString());
        return json.readTree(response.body());
    }

    public static void main(String[] args) throws Exception {
        Path file = Path.of("background.mp4");
        JsonNode upload = call("POST", "/uploads", """
            {"fileName": "background.mp4", "sizeBytes": %d}
            """.formatted(Files.size(file)));
        String uploadId = upload.get("id").asText();
        String uploadUrl = upload.get("url").asText();
    }
}
Field Description
fileName The file's name, up to 255 characters. Its extension must be a supported file type, or .zip for a project ZIP.
sizeBytes The exact size in bytes, up to 8 GB. A file over its kind's limit, such as a .png over 128 MB, or over your plan's project size, is refused here, before you upload anything.

The response is 201 Created. Its id is what you later pass as uploadId or zipUploadId. Up to 100 MB, url is where you send the file:

{ "id": "1c9d…", "status": "open", "url": "https://…", "method": "PUT", "expiresAt": "2026-11-04T20:00:00+00:00", "multipart": null, "error": null }

Above 100 MB, url is null, and multipart lists one URL per part instead (multipart uploads).

2. PUT the bytes

curl -s -X PUT --upload-file background.mp4 "$UPLOAD_URL"
with open("background.mp4", "rb") as file:
    requests.put(upload_url, data=file)
await fetch(uploadUrl, { method: "PUT", body: await readFile("background.mp4") });
$file = fopen("background.mp4", "rb");
$ch = curl_init($uploadUrl);
curl_setopt_array($ch, [
    CURLOPT_UPLOAD => true,
    CURLOPT_INFILE => $file,
    CURLOPT_INFILESIZE => filesize("background.mp4"),
    CURLOPT_RETURNTRANSFER => true,
]);
curl_exec($ch);
fclose($file);
uri = URI(upload_url)
request = Net::HTTP::Put.new(uri)
File.open("background.mp4", "rb") do |file|
  request.body_stream = file
  request["Content-Length"] = file.size.to_s
  Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
end
req, err := http.NewRequest("PUT", uploadURL, file)
if err != nil {
	panic(err)
}
req.ContentLength = info.Size()
res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
res.Body.Close()
await using var file = File.OpenRead("background.mp4");
await http.PutAsync(uploadUrl, new StreamContent(file));
HttpRequest put = HttpRequest.newBuilder(URI.create(uploadUrl))
    .PUT(HttpRequest.BodyPublishers.ofFile(file))
    .build();
HttpClient.newHttpClient().send(put, HttpResponse.BodyHandlers.discarding());

Send the file as the raw request body, without an Authorization header: the URL is already signed. It accepts exactly sizeBytes bytes, and storage refuses a body of any other size.

3. Complete it

curl -s -X POST $BLITFRAME/uploads/$UPLOAD_ID/complete \
  -H "Authorization: Bearer $BLITFRAME_API_KEY" \
  -H "Prefer: wait=30" | jq '{status, error}'
completed = requests.post(f"{api}/uploads/{upload_id}/complete", headers={**headers, "Prefer": "wait=30"}).json()
print(completed["status"], completed["error"])
const completed = await (
  await fetch(`${api}/uploads/${uploadId}/complete`, { method: "POST", headers: { ...headers, Prefer: "wait=30" } })
).json();
console.log(completed.status, completed.error);
$completed = call("POST", "/uploads/$uploadId/complete", headers: ["Prefer: wait=30"]);
print_r([$completed["status"], $completed["error"]]);
completed = call("POST", "/uploads/#{upload_id}/complete", nil, { "Prefer" => "wait=30" })
p completed["status"], completed["error"]
// also import "fmt"
completed := call("POST", "/uploads/"+uploadID+"/complete", nil, map[string]string{"Prefer": "wait=30"})
fmt.Println(completed["status"], completed["error"])
var completed = await call(HttpMethod.Post, $"/uploads/{uploadId}/complete", null, ("Prefer", "wait=30"));
Console.WriteLine($"{completed["status"]} {(string?)completed["error"]?["message"] ?? "null"}");
JsonNode completed = call("POST", "/uploads/" + uploadId + "/complete", null, "Prefer", "wait=30");
System.out.println(completed.get("status").asText() + " " + completed.get("error"));

Complete every upload once its bytes are in place. A single-PUT upload needs no body, and a multipart upload lists its parts (below). Blitframe then checks the file as an edit would: its type, contents and limits. A font is also prepared for rendering.

Prefer: wait=30 holds the answer until the upload is ready or failed, or 30 seconds pass. Without it, the answer comes at once. Prefer: wait=N takes up to 50 seconds. The upload's status is one of:

status Meaning
open Created, not completed yet.
processing Being checked. Most files take seconds. Several gigabytes can take minutes.
ready Checked. An edit, render or import can use it. A ZIP is ready as soon as it is completed, because its import checks it.
failed error says why.
{ "id": "1c9d…", "status": "failed", "url": null, "method": null, "expiresAt": "2026-11-04T20:00:00+00:00", "multipart": null, "error": { "code": "invalid_request", "message": "'background.mp4' is not a valid .mp4 file." } }

GET /v1/uploads/{uploadId} returns the upload and takes Prefer: wait=N too. Completing again is harmless: it answers with the upload as it is.

If the check failed with interrupted, it stopped on Blitframe's side. Complete the upload again to check it again, without sending the bytes again. An upload is checked at most three times: after that it fails with check_limit, and you upload the file again. Any other failure is about the file itself and is final, so create a new upload.

4. Use it

Each upload can be used once: by an edit, a ZIP import or one render's replacements, including one render of a batch. Use it within 1 hour of creating it, or 24 hours for a multipart upload. After that it expires and is deleted, whether it is ready or not (limits).

In an edit

Name the upload as a file of an edit (POST /v1/projects/{projectId}/versions):

{ "files": [{ "path": "video/background.mp4", "uploadId": "1c9d…" }] }

The path must end in the upload's extension, letter case aside. To add a composition, create its upload with the name data.json. The file was already checked, so the edit is quick whatever its size.

An edit takes only ready uploads. Otherwise it answers 409 upload_incomplete, upload_processing or upload_failed (refusals).

In a render

A replacement's new image or video names the upload (replacements in a render):

{ "layer": "/layers/3", "file": { "path": "images/product-es.png", "uploadId": "1c9d…" } }

A render takes only ready uploads too (when an upload is refused). Queueing the render holds the upload until the render's version is made.

As a new project

Upload a ZIP and create the project from it:

POST /v1/projects
{ "name": "Summer ad", "zipUploadId": "1c9d…", "fontLicenseAccepted": true }

The ZIP becomes the project's version 1, and its folder structure becomes the file paths.

  • Put data.json at the root of the ZIP or in a folder. When one data.json is shallower than every other, the folder it is in becomes the project's root. Files outside that folder keep their ZIP path. Zipping the folder itself gives you that.
  • When two data.json files are equally shallow, such as a/data.json and b/data.json, the ZIP's own root stays the root, so the version has no data.json at its root.
  • A ZIP without data.json still imports. Its version's problems say the file is missing, and it can't render until you add one.
  • Files your system adds when zipping are skipped: __MACOSX/, .DS_Store, macOS ._ files, Thumbs.db and desktop.ini. Every other file must be a supported type.
  • A ZIP with font files needs "fontLicenseAccepted": true (fonts).

Into an existing project

Import a ZIP as the project's next version:

POST /v1/projects/{projectId}/package
{ "zipUploadId": "1c9d…", "expectedHeadVersionId": "b7e2…" }

The new version holds exactly the ZIP's files and becomes the head. Files of the head that are not in the ZIP are not carried over. It keeps the head's soundtrack while the ZIP still holds that audio file. The ZIP follows the same rules as for a new project, fontLicenseAccepted included. The response is 201 Created with the new version.

The head is main's, or that of the variation you name in "variation". expectedHeadVersionId is optional. With it, that head must still be that version when the import finishes, or you get 409 head_moved and the upload stays usable. Without it, the ZIP replaces whatever the head is then.

Send an Idempotency-Key header with either request, so a retry after a lost answer can't import the ZIP twice. For 24 hours, a retry with the same key answers like the first request: with the project or version it made, or, if the first answered 202 Accepted, with the import as it is now. If the first import failed, the retry imports again (retrying safely).

Large ZIPs

An import holds the request for up to 50 seconds, and Prefer: wait=N shortens that. If the import finishes in time, you get the new project or version, or the import's error. A project created from a ZIP that fails is not kept. If the ZIP is still importing, you get 202 Accepted with the import:

{
  "id": "e41c…",
  "projectId": "9a0f…",
  "status": "importing",
  "versionId": null,
  "error": null,
  "createdAt": "2026-11-07T09:30:00+00:00",
  "finishedAt": null
}

Get the import with GET /v1/projects/{projectId}/package/{importId} while status is queued or importing. It takes Prefer: wait=N too. It ends succeeded, with the new versionId, or failed, with an error (code and message) as the import request would have answered.

Imports run one at a time per workspace, in the order sent. An import that stops partway fails with interrupted: send it again. Limits says how many imports can wait. Import details says what else can make one fail, and refusals why one is refused.

Multipart uploads

Above 100 MB, the file goes up in parts of partSize bytes (64 MB), and the last part holds the rest. The response to step 1 lists a URL per part:

{
  "id": "7a41…",
  "status": "open",
  "url": null,
  "method": null,
  "expiresAt": "2026-11-05T20:00:00+00:00",
  "multipart": {
    "partSize": 67108864,
    "partCount": 4,
    "urlsExpireAt": "2026-11-04T21:00:00+00:00",
    "parts": [{ "partNumber": 1, "url": "https://…" }, { "partNumber": 2, "url": "https://…" }, …]
  },
  "error": null
}
  1. PUT each part to its URL. Part 1 is bytes 0 to partSize - 1, part 2 the next partSize bytes, and so on. Each URL accepts exactly its part's size. Parts can go in parallel.
  2. Keep the ETag header of each PUT response.
  3. Complete the upload with every part's number and ETag.

The examples continue from step 1, with an upload over 100 MB, in place of steps 2 and 3. Replace the values in etags with the ETags you kept, in part order:

curl -s -X POST $BLITFRAME/uploads/$UPLOAD_ID/complete \
  -H "Authorization: Bearer $BLITFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parts":[{"partNumber":1,"etag":"\"5d41…\""},{"partNumber":2,"etag":"\"7c2b…\""},{"partNumber":3,"etag":"\"9e10…\""},{"partNumber":4,"etag":"\"0b8f…\""}]}'
etags = ['"5d41…"', '"7c2b…"', '"9e10…"', '"0b8f…"']
parts = [{"partNumber": n, "etag": etag} for n, etag in enumerate(etags, start=1)]
completed = requests.post(f"{api}/uploads/{upload_id}/complete", headers=headers, json={"parts": parts}).json()
print(completed["status"], completed["error"])
const etags = ['"5d41…"', '"7c2b…"', '"9e10…"', '"0b8f…"'];
const parts = etags.map((etag, i) => ({ partNumber: i + 1, etag }));
const completed = await (
  await fetch(`${api}/uploads/${uploadId}/complete`, { method: "POST", headers: json, body: JSON.stringify({ parts }) })
).json();
console.log(completed.status, completed.error);
$etags = ['"5d41…"', '"7c2b…"', '"9e10…"', '"0b8f…"'];
$parts = [];
foreach ($etags as $i => $etag) {
    $parts[] = ["partNumber" => $i + 1, "etag" => $etag];
}
$completed = call("POST", "/uploads/$uploadId/complete", ["parts" => $parts]);
print_r([$completed["status"], $completed["error"]]);
etags = ['"5d41…"', '"7c2b…"', '"9e10…"', '"0b8f…"']
parts = etags.map.with_index(1) { |etag, n| { partNumber: n, etag: etag } }
completed = call("POST", "/uploads/#{upload_id}/complete", { parts: parts })
p completed["status"], completed["error"]
// also import "fmt"
etags := []string{`"5d41…"`, `"7c2b…"`, `"9e10…"`, `"0b8f…"`}
parts := []map[string]any{}
for i, etag := range etags {
	parts = append(parts, map[string]any{"partNumber": i + 1, "etag": etag})
}
completed := call("POST", "/uploads/"+uploadID+"/complete", map[string]any{"parts": parts}, nil)
fmt.Println(completed["status"], completed["error"])
string[] etags = ["\"5d41…\"", "\"7c2b…\"", "\"9e10…\"", "\"0b8f…\""];
var parts = etags.Select((etag, i) => new { partNumber = i + 1, etag });
var completed = await call(HttpMethod.Post, $"/uploads/{uploadId}/complete", new { parts });
Console.WriteLine($"{completed["status"]} {(string?)completed["error"]?["message"] ?? "null"}");
String[] etags = {"\"5d41…\"", "\"7c2b…\"", "\"9e10…\"", "\"0b8f…\""};
var parts = json.createArrayNode();
for (int i = 0; i < etags.length; i++) {
    parts.addObject().put("partNumber", i + 1).put("etag", etags[i]);
}
JsonNode completed = call("POST", "/uploads/" + uploadId + "/complete", json.createObjectNode().set("parts", parts).toString());
System.out.println(completed.get("status").asText() + " " + completed.get("error"));

The response is the upload, checked as in step 3. If the completion leaves out a part, it is refused and the upload stays open. Upload the missing parts and complete it again.

Part URLs last 1 hour, and the upload stays open for 24 hours. To resume after the URLs expired, get fresh ones with POST /v1/uploads/{uploadId}/parts. Then upload only the parts you are missing:

POST /v1/uploads/7a41…/parts
{ "partNumbers": [3, 4] }

Leave out partNumbers, or send no body, to get every part again. The response is the multipart object above.

Browser code can upload parts directly: the upload URLs accept cross-origin PUT requests and expose the ETag response header.

Delete an upload

DELETE /v1/uploads/{uploadId} deletes an upload you no longer need. It also discards the parts of an open multipart upload. A workspace can hold 100 unexpired uploads. Delete the ones you won't use, or let them expire (which uploads count).

Copy files from another version

Add a file that is already in any version of your workspace, in any project, to an edit without uploading it:

{ "files": [{ "path": "images/logo.png", "fromVersionId": "4f0a…", "fromPath": "brand/logo.png" }] }

fromPath defaults to path. The file type must stay the same: a .png can't become a .jpg. The composition, the data.json at the root, can only be copied from another version's root data.json.

To turn another JSON file into the composition, send its content or an upload named data.json. To keep a copy of the composition at another path, send its content or an upload with any other .json name. An upload named data.json is always the composition.

To find files to reuse, list a project's files with GET /v1/projects/{projectId}/files (project files).

File capabilities

GET /v1/files/capabilities returns every supported file extension with its limits, and the upload, ZIP and edit limits. maxInlineEditBytes is the largest edit request body. Use it for file pickers and to check a file before you upload it. The server still checks every file. You can cache the answer for 5 minutes.

{
  "upload": { "maxSizeBytes": 8589934592, "singlePutMaxBytes": 104857600, "multipartPartSizeBytes": 67108864, "singleUploadLifetimeSeconds": 3600, "multipartUploadLifetimeSeconds": 86400, "partUrlLifetimeSeconds": 3600 },
  "zip": { "maxFiles": 5000, "maxUncompressedBytes": 8589934592, "maxCompressionRatio": 200 },
  "maxFilesPerVersion": 5000,
  "maxInlineEditBytes": 67108864,
  "compositionPath": "data.json",
  "textFittingPath": "text_fitting.json",
  "files": [
    { "extension": ".mp4", "kind": "video", "contentType": "video/mp4", "maxSizeBytes": 4294967296, "defaultFolder": "videos/", "maxWidth": 8192, "maxHeight": 8192, "maxDurationSeconds": 3600, "fontLicenseRequired": false },
    { "extension": ".png", "kind": "image", "contentType": "image/png", "maxSizeBytes": 134217728, "defaultFolder": "images/", "maxWidth": 8192, "maxHeight": 8192, "maxDurationSeconds": 3600, "fontLicenseRequired": false },
    { "extension": ".ttf", "kind": "font", "contentType": "font/ttf", "maxSizeBytes": 67108864, "defaultFolder": "fonts/", "maxWidth": null, "maxHeight": null, "maxDurationSeconds": null, "fontLicenseRequired": true },
    …
  ]
}

defaultFolder is a suggestion: any valid path works. fontLicenseRequired marks the font types, which need fontLicenseAccepted: true when added. On images, maxDurationSeconds applies to animated GIF and WebP.

Details

Refusals

A refused edit or import changes nothing.

Request Answer When
Create 400 invalid_request fileName is missing, over 255 characters, or not a supported file type or .zip. Or sizeBytes is not between 1 byte and 8 GB.
Create 413 too_large sizeBytes is over the limit for the file's kind, such as a .png over 128 MB (file capabilities).
Create 403 project_too_large sizeBytes is over your plan's project size, for a file other than a ZIP. A ZIP is checked when it is imported, and refused here only when it is too large to import over any head of your workspace.
Create 409 upload_limit The workspace already holds 100 unexpired uploads (delete an upload).
Create, complete, edit or import 402 insufficient_render_seconds or 402 payment_disputed The workspace can't render: it has no free trial, its trial or plan has ended, a failed payment is unpaid, or a payment is disputed. It can't add files either until that is fixed, and a completed upload fails with the same error. Running out of render seconds alone doesn't stop uploads. Reading, downloading, exporting and deleting still work.
Complete 400 invalid_request The bytes are missing, or not the declared size.
Complete a multipart upload 400 invalid_request parts does not list each part once, with its ETag. The upload stays open: upload the missing parts and complete it again.
Edit 400 invalid_request The upload does not exist, belongs to another workspace or has expired. Or a different request already used it (edits that name uploads).
Edit 404 not_found A file's fromVersionId doesn't exist or belongs to another workspace.
Edit 400 invalid_request The fromVersionId has no file at fromPath, or the copy changes the file's type.
Edit 400 invalid_request The path does not end in the upload's extension. Or the upload was created as data.json and the path is another one, or the other way round.
Edit or import 409 upload_incomplete The upload has not been completed.
Edit 409 upload_processing The upload is still being checked. The message names every upload of the edit still being checked, and the Retry-After header says when to try again.
Edit 409 upload_failed The upload failed its check. The message gives the upload's own error code and message.
Import 400 invalid_request The upload does not exist, belongs to another workspace, has expired, is not a .zip, or was created more than 46 hours ago.
Import 404 not_found The project has no such variation.
Edit or import 403 project_too_large The version's files would total more than your plan's project size. A ZIP is refused on its upload's size, before it is read, when it could not fit over the head it replaces, and otherwise on the sizes its file list declares, before its files are read.
Import 409 head_moved expectedHeadVersionId is no longer the head when the import finishes. The upload stays usable.
Import 409 import_limit 10 imports are already waiting or running.

A render that names an upload is refused in the same ways (when an upload is refused).

Import details

Queueing an import extends its upload's expiry to a day from then, but never past 47 hours after the upload was created. An import that waited until its upload has less than an hour left fails with invalid_request when it starts. So does an import whose upload was deleted while it waited. Upload the ZIP again in either case.

A finished import's status is kept for 7 days. After that, getting it returns 404.