Uploading large files
View as MarkdownSend 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.jsonat the root of the ZIP or in a folder. When onedata.jsonis 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.jsonfiles are equally shallow, such asa/data.jsonandb/data.json, the ZIP's own root stays the root, so the version has nodata.jsonat its root. - A ZIP without
data.jsonstill imports. Its version'sproblemssay 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.dbanddesktop.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
}
PUTeach part to its URL. Part 1 is bytes0topartSize - 1, part 2 the nextpartSizebytes, and so on. Each URL accepts exactly its part's size. Parts can go in parallel.- Keep the
ETagheader of eachPUTresponse. - 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.