Return 499 for canceled instance restores

[sjmiller609]

Summary

• classify caller-canceled restore requests as HTTP 499 instead of 500
• lower cancellation logging from error to debug
• document and generate the typed 499 API response
• keep unexpected restore failures classified as 500

Validation

• go test ./cmd/api/api -run 'TestRestoreInstance_ErrorMapping|TestInstanceActions_ImageNotFoundMapsTo404' -count=1
• go test ./lib/oapi -count=1
• go vet ./cmd/api/api ./lib/oapi
• go build ./cmd/api

The full cmd/api/api package suite was attempted but requires host capabilities and tools unavailable locally (mkfs.erofs, network bridge permissions, and authenticated Docker pulls). The focused handler tests pass.

---

Note

Low Risk
Narrow change to restore error handling and API documentation; success paths and security-sensitive logic are untouched.

Overview
Restore now treats caller cancellation as HTTP 499 (client_closed_request) instead of a generic 500, when RestoreInstance returns an error wrapping context.Canceled. Cancellations are logged at debug rather than as internal errors.

The OpenAPI spec documents the new 499 response on POST /instances/{id}/restore, and generated lib/oapi types handle encoding/decoding it. TestRestoreInstance_ErrorMapping locks in 499 vs 500 mapping; other restore error paths (404, 409, etc.) are unchanged.

^{Reviewed by Cursor Bugbot for commit 7ca2e3d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[yummybomb]

PR returns 499 to canceled instance restores, very straightforward. lgtm

[github-actions]

-->

✱ stlc build

✅ go code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

116 files generated at cf8022d (pushed)

go get github.com/kernel/hypeman-go-staging@cf8022d3a0b1dd8cabd16e1b7dde0a7b1b193b51

✅ python code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

230 files generated at 08d46ad (pushed)

✅ typescript code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

138 files generated at c0bd22f (pushed)

Diagnostics: ❗ 0 new / 1 total error, 💡 0 new / 5 total note

Level	Code	Message	Targets

Build metadata

Build	bd_76CwCDmn-gallant-mane
Timestamp	2026-08-25T18:56:04.557Z
stlc	8413509
Spec hash	54167c86eaa9
Config hash	55e15f6f4434

---

This comment is auto-generated by stlc and is kept up to date as you push.
If you push new commits, re-run this workflow to update this comment.
Last updated: 2026-08-25 18:56:41 UTC