Result box: color-code by status + friendly error messages from error codes (#105)

- Backend create/can validation paths emit machine-readable error codes
  (slug_taken, slug_invalid, content_empty, content_too_large,
  expiry_invalid, rate_limited, ...) alongside the human message
- new.html JS maps codes to plain-language guidance with generic fallback
- Result card colored via --ok/--err/--warn left border (result-ok/err/warn)
- docs/API.md error section documents the code field
- Tests assert the code on every validation path

internal/api/cans.go

@@ -28,7 +28,7 @@ func (a *apiServer) handleCreateCan(w http.ResponseWriter, r *http.Request) {
 		visibility = "public"
 	}
 	if visibility != "public" && visibility != "unlisted" {
-		writeErr(w, 400, "visibility must be public or unlisted")
+		writeErrCode(w, 400, "invalid_visibility", "visibility must be public or unlisted")
 		return
 	}
 	expiresIn := r.FormValue("expires_in")
@@ -40,13 +40,13 @@ func (a *apiServer) handleCreateCan(w http.ResponseWriter, r *http.Request) {
 	if expiresIn != "" {
 		d, err := time.ParseDuration(expiresIn)
 		if err != nil {
-			writeErr(w, 400, "invalid expires_in")
+			writeErrCode(w, 400, "expiry_invalid", "invalid expires_in")
 			return
 		}
 		// #60/#48: clamp at the API boundary like the pastes API does -
 		// reject zero/negative and durations past the 1-year UI cap.
 		if !store.ValidExpiry(d) {
-			writeErr(w, 400, "expires_in must be between 1 minute and 1 year")
+			writeErrCode(w, 400, "expiry_invalid", "expires_in must be between 1 minute and 1 year")
 			return
 		}
 		t := now + int64(d.Seconds())
@@ -71,7 +71,7 @@ func (a *apiServer) handleCreateCan(w http.ResponseWriter, r *http.Request) {
 	if err != nil {
 		switch err {
 		case store.ErrSlugTaken, store.ErrInvalidSlug, store.ErrReservedSlug:
-			writeErr(w, 409, err.Error())
+			writeErrCode(w, 409, createErrCode(err), err.Error())
 		default:
 			writeErr(w, 500, "db error")
 		}
@@ -137,7 +137,7 @@ func (a *apiServer) handleCreateCan(w http.ResponseWriter, r *http.Request) {
 
 	if itemCount == 0 {
 		a.store.DeleteCan(canID)
-		writeErr(w, 400, "can needs at least one item (files or json_items)")
+		writeErrCode(w, 400, "content_empty", "can needs at least one item (files or json_items)")
 		return
 	}
 

internal/api/issue105_errorcode_test.go

@@ -0,0 +1,123 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// #105: every validation path on create returns a machine-readable `code`
+// alongside the human `error` message, so the new-page JS can map known
+// codes to plain-language guidance.
+
+func decodeErr(t *testing.T, rec *httptest.ResponseRecorder) (status int, errMsg, code string) {
+	t.Helper()
+	var got struct {
+		Error string `json:"error"`
+		Code  string `json:"code"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+		t.Fatalf("bad json: %v (%s)", err, rec.Body.String())
+	}
+	return rec.Code, got.Error, got.Code
+}
+
+func postCreate(h http.Handler, body string) *httptest.ResponseRecorder {
+	req := httptest.NewRequest("POST", "/api/pastes", strings.NewReader(body))
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	return rec
+}
+
+func TestErrorCodeContentEmpty(t *testing.T) {
+	h := testServer(t).routes()
+	_, _, code := decodeErr(t, postCreate(h, `{"content":"   "}`))
+	if code != "content_empty" {
+		t.Fatalf("code = %q, want content_empty", code)
+	}
+}
+
+func TestErrorCodeContentTooLarge(t *testing.T) {
+	h := testServer(t).routes()
+	big := strings.Repeat("x", 6*1024*1024) // over the 5MB test cap
+	_, _, code := decodeErr(t, postCreate(h, `{"content":"`+big+`"}`))
+	if code != "content_too_large" {
+		t.Fatalf("code = %q, want content_too_large", code)
+	}
+}
+
+func TestErrorCodeSlugTaken(t *testing.T) {
+	h := testServer(t).routes()
+	if rec := postCreate(h, `{"content":"a","custom_slug":"taken-slug"}`); rec.Code != 201 {
+		t.Fatalf("seed create: %d %s", rec.Code, rec.Body.String())
+	}
+	_, _, code := decodeErr(t, postCreate(h, `{"content":"b","custom_slug":"taken-slug"}`))
+	if code != "slug_taken" {
+		t.Fatalf("code = %q, want slug_taken", code)
+	}
+}
+
+func TestErrorCodeSlugInvalid(t *testing.T) {
+	h := testServer(t).routes()
+	_, _, code := decodeErr(t, postCreate(h, `{"content":"a","custom_slug":"bad slug!"}`))
+	if code != "slug_invalid" {
+		t.Fatalf("code = %q, want slug_invalid", code)
+	}
+}
+
+func TestErrorCodeExpiryInvalid(t *testing.T) {
+	h := testServer(t).routes()
+	_, _, code := decodeErr(t, postCreate(h, `{"content":"a","expires_in":"2s"}`))
+	if code != "expiry_invalid" {
+		t.Fatalf("code = %q, want expiry_invalid", code)
+	}
+}
+
+func TestErrorCodeRateLimited(t *testing.T) {
+	h := testServer(t).routes()
+	var code string
+	for i := 0; i < 20; i++ {
+		_, _, code = decodeErr(t, postCreate(h, `{"content":"a"}`))
+		if code == "rate_limited" {
+			return
+		}
+	}
+	t.Fatalf("never got rate_limited, last code = %q", code)
+}
+
+func TestErrorCodeCanValidation(t *testing.T) {
+	h := testServer(t).routes()
+
+	post := func(fields map[string]string) *httptest.ResponseRecorder {
+		var b strings.Builder
+		for k, v := range fields {
+			b.WriteString("--B\r\nContent-Disposition: form-data; name=\"" + k + "\"\r\n\r\n" + v + "\r\n")
+		}
+		b.WriteString("--B--\r\n")
+		req := httptest.NewRequest("POST", "/api/pastes/can", strings.NewReader(b.String()))
+		req.Header.Set("Content-Type", "multipart/form-data; boundary=B")
+		rec := httptest.NewRecorder()
+		h.ServeHTTP(rec, req)
+		return rec
+	}
+
+	// bad visibility
+	if _, _, code := decodeErr(t, post(map[string]string{"title": "x", "visibility": "nope"})); code != "invalid_visibility" {
+		t.Fatalf("visibility code = %q, want invalid_visibility", code)
+	}
+
+	// invalid expiry
+	if _, _, code := decodeErr(t, post(map[string]string{"title": "x", "expires_in": "1s"})); code != "expiry_invalid" {
+		t.Fatalf("expiry code = %q, want expiry_invalid", code)
+	}
+
+	// slug taken on can create
+	if rec := postCreate(h, `{"content":"a","custom_slug":"can-slug"}`); rec.Code != 201 {
+		t.Fatalf("seed create: %d", rec.Code)
+	}
+	if _, _, code := decodeErr(t, post(map[string]string{"title": "x", "custom_slug": "can-slug", "json_items": `[{"title":"a","content":"b"}]`})); code != "slug_taken" {
+		t.Fatalf("can slug code = %q, want slug_taken", code)
+	}
+}

internal/api/ratelimit.go

@@ -113,7 +113,7 @@ func rateLimitAdmin(r *http.Request) bool {
 // writeRateLimited responds 429 with Retry-After based on refill rate.
 func writeRateLimited(w http.ResponseWriter, retryAfterSecs int) {
 	w.Header().Set("Retry-After", strconv.Itoa(retryAfterSecs))
-	writeErr(w, 429, "rate limit exceeded")
+	writeErrCode(w, 429, "rate_limited", "rate limit exceeded")
 }
 
 // setRateLimitHeaders sets informational X-RateLimit headers for create/guess.

internal/api/server.go

@@ -6,6 +6,7 @@ import (
 	"context"
 	"database/sql"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"html/template"
 	"net/http"
@@ -51,6 +52,30 @@ func writeErr(w http.ResponseWriter, status int, msg string) {
 	writeJSON(w, status, map[string]string{"error": msg})
 }
 
+// writeErrCode emits a JSON error with a machine-readable code (#105): the
+// new-page JS maps known codes to plain-language messages, API consumers get
+// the stable `code` field alongside the human `error` text.
+func writeErrCode(w http.ResponseWriter, status int, code, msg string) {
+	writeJSON(w, status, map[string]string{"error": msg, "code": code})
+}
+
+// createErrCode maps a store.CreatePaste/CreateCan error to its UI error
+// code (#105).
+func createErrCode(err error) string {
+	switch {
+	case errors.Is(err, store.ErrSlugTaken):
+		return "slug_taken"
+	case errors.Is(err, store.ErrReservedSlug):
+		return "slug_reserved"
+	case errors.Is(err, store.ErrInvalidSlug):
+		return "slug_invalid"
+	case strings.Contains(err.Error(), "expires_in"):
+		return "expiry_invalid"
+	default:
+		return "invalid_request"
+	}
+}
+
 // Routes returns the HTTP handler for the server.
 func (a *apiServer) Routes() http.Handler {
 	return a.routes()
@@ -158,14 +183,18 @@ func (a *apiServer) handleCreatePaste(w http.ResponseWriter, r *http.Request) {
 	var p store.Paste
 	if err := json.NewDecoder(r.Body).Decode(&p); err != nil {
 		if isBodyTooLarge(err) { // #68: body cut off by MaxBytesReader
-			writeBodyTooLarge(w)
+			writeErrCode(w, http.StatusRequestEntityTooLarge, "content_too_large", "request body too large")
 			return
 		}
 		writeErr(w, 400, "invalid json body")
 		return
 	}
 	if status, msg := checkContent(p.Content, s.MaxContentBytes); status != 0 {
-		writeErr(w, status, msg)
+		if status == http.StatusRequestEntityTooLarge {
+			writeErrCode(w, status, "content_too_large", msg)
+		} else {
+			writeErrCode(w, status, "content_empty", msg)
+		}
 		return
 	}
 	// #86: bound free-form metadata at create time
@@ -203,7 +232,7 @@ func (a *apiServer) handleCreatePaste(w http.ResponseWriter, r *http.Request) {
 	p.ViewerID = currentViewerID(r)
 	created, err := a.store.CreatePaste(&p)
 	if err != nil {
-		writeErr(w, 400, err.Error())
+		writeErrCode(w, 400, createErrCode(err), err.Error())
 		return
 	}
 	writeJSON(w, 201, map[string]any{