For developers
When a publish is refused
A refused publish changes nothing — your old site keeps serving. Every refusal names the check that stopped it, and everything above that check genuinely passed.
The checks
Every zip goes through the same seven checks, whichever door it came through, and they run in this order.
| Check | What it looks for | If it fails |
|---|---|---|
| Files received | The whole upload arrived intact | Re-send it; the connection dropped |
| Archive readable | We can open it and read its contents | Re-export the folder as a .zip — some tools produce archives we cannot read |
| File paths safe | No file writes outside your site's folder | Zip from inside the folder, not above it |
| No shortcut links | No symbolic links | Replace the shortcuts with real files |
| File sizes within limits | No single file over 25 MB, no more than 20,000 files | Compress or remove the big one; node_modules and .git are the usual file-count culprits |
| Fits your storage | The unpacked site fits in 1 GB | Trim it. Images are almost always the bulk; exporting them as WebP usually halves it |
| Published | Swapped in as the live version | — |
An archive with nothing publishable in it fails at Archive readable. An archive that is missing index.html at the top does not fail at all — it publishes, and the site's home address then answers 404. Zip the folder's contents, not the folder itself; a wrapper folder is the usual cause, and only the GitHub door strips one.
Status codes
| Code | Error | What it means |
|---|---|---|
| 401 | unauthorized | Missing, malformed or revoked token. |
| 404 | not_found | No such site, or not this token's. Deliberately the same answer. |
| 409 | deploy_in_progress | One is already running. Wait for it. |
| 409 | studio_managed | This site is edited in the browser; publishing files would overwrite that work. |
| 413 | too_large | Over 256 MB compressed. |
| 429 | rate_limited | Retry-After says how long. |
| 400 | empty_body | No zip arrived. |
| 400 | upload_interrupted | The connection dropped mid-upload. |
Published, but not visible
Files can be accepted while the site does not serve. That is not a failure — it is a site that is unpaid, or held for review. whoami reports it as serving: false, and the portal says which. Your files are safe and go live the moment the site does.
Something else
An unexpected error still prints its stack rather than hiding it — somebody has to be able to report it. Everything we anticipated is a sentence and a fix, never a stack trace at somebody publishing their first website.