Error shape
{ "error": "An image file is required in the image field." }Use the HTTP status to choose how to handle an error. The error string gives a readable explanation; avoid matching exact message text in application logic.
Status codes
| Status | Cause | What to do |
|---|---|---|
400 |
Malformed multipart request or a missing image file field |
Send a file in image; let the client create the multipart boundary. |
413 |
File or request body is too large | Use an image no larger than 10 MiB. The complete multipart request also has an overhead limit. |
415 |
File bytes do not identify a supported PNG or JPEG | Export a real PNG or JPEG from the original artwork. |
422 |
Image exceeds 4 million pixels or cannot be decoded | Resize the image or open and re-export it, then try again. |
502 |
The configured conversion service could not be reached | Retry later. Preserve the selected file and let the person retry. |
An infrastructure failure may return another status or a non-JSON response. Handle that case without assuming every failed request contains an error property.
Handle failures safely
const response = await fetch("/api/vectorize", { method: "POST", body: form });
const result = await response.json().catch(() => null);
if (!response.ok) {
const message = result?.error ?? "Conversion failed. Please try again.";
throw new Error(message);
}
if (typeof result?.svg !== "string") {
throw new Error("The server returned an unexpected response.");
}Retrying
Correct 400, 413, 415, and 422 inputs before retrying. Repeating an unchanged invalid request will not fix it. For a network or service failure, offer a deliberate retry and avoid sending repeated parallel uploads automatically.