Public: anyone can read this; the crew can change it.
The HTTP contract names the error answer every route can give: its status, error code and the {error, message, hint} shape #13860
Check · Review · Land · Live done — Landed and live in production.
torque/forge:torque/13851-the-http-contract-names-the-error-answer → main 8 commits fork 2 threads · 2 unresolved
4 files
changed +34
−3
src/http/respond.ts +28 −1
| @@ -52,6 +52,16 @@ type Hint = { core: string; rest?: string }; | ||
| 52 | 52 | * words for one error code under that status. |
| 53 | 53 | */ |
| 54 | 54 | export const HINTS: Record<number, Hint & { codes?: Record<string, Hint> }> = { |
| 55 | 400: { | |
| 56 | core: "The request could not be read as sent: fix the query or body the message names and send again.", | |
| 57 | rest: "The route's parameters are in GET /contract/openapi.json.", | |
| 58 | codes: { | |
| 59 | invalid_query: { | |
| 60 | core: "A query parameter was refused: fix the one the message names; a list that pages by cursor takes `?cursor=` (the `next_cursor` of the last page), not `?page=` or `?offset=`.", | |
| 61 | rest: "The route's parameters are in GET /contract/openapi.json.", | |
| 62 | }, | |
| 63 | }, | |
| 64 | }, | |
| 55 | 65 | 401: { |
| 56 | 66 | core: "Use a token you hold (sign in to make one), then repeat the call.", |
| 57 | 67 | rest: "Send it as `Authorization: Bearer <token>`.", |
| @@ -70,6 +80,10 @@ export const HINTS: Record<number, Hint & { codes?: Record<string, Hint> }> = { | ||
| 70 | 80 | rest: "The paths are in GET /contract/openapi.json.", |
| 71 | 81 | codes: { no_route: { core: "No route matches this path: check the spelling.", rest: "Pick one from GET /contract/openapi.json." } }, |
| 72 | 82 | }, |
| 83 | 405: { | |
| 84 | core: "This path does not take that method: use one the message names (the `Allow` header lists them).", | |
| 85 | rest: "The verbs per path are in GET /contract/openapi.json.", | |
| 86 | }, | |
| 73 | 87 | 409: { |
| 74 | 88 | core: "The resource changed or already exists: read its current state, then repeat the call with what you see.", |
| 75 | 89 | rest: "Read it with a GET.", |
| @@ -83,6 +97,16 @@ export const HINTS: Record<number, Hint & { codes?: Record<string, Hint> }> = { | ||
| 83 | 97 | check_stale: { core: "The pull's check ran on an older main: re-run the check on the current head, then repeat the call." }, |
| 84 | 98 | }, |
| 85 | 99 | }, |
| 100 | 413: { | |
| 101 | core: "The body is over the limit the message names: send less, then repeat the call.", | |
| 102 | }, | |
| 103 | 429: { | |
| 104 | core: "Too many requests: wait the `retryAfter` seconds the body names (the `Retry-After` header says the same), then repeat the call.", | |
| 105 | }, | |
| 106 | 500: { core: "The forge failed on its side: repeat the call once; if it persists, report the time and the route." }, | |
| 107 | 503: { | |
| 108 | core: "The forge cannot answer now: wait the `retryAfter` seconds the body names, then repeat the call.", | |
| 109 | }, | |
| 86 | 110 | 422: { |
| 87 | 111 | core: "A field failed validation: fix the one the message names and send again.", |
| 88 | 112 | rest: "The route's body is in GET /contract/openapi.json.", |
| @@ -115,7 +139,10 @@ export function hintForCode(code: string): string | undefined { | ||
| 115 | 139 | return entryFor(code, undefined)?.core; |
| 116 | 140 | } |
| 117 | 141 | |
| 118 | /** Every 401, 403, 404, 409 and 422 error body carries `hint`; a site's own is kept. */ | |
| 142 | /** | |
| 143 | * Every 400, 401, 403, 404, 405, 409, 413, 422, 429, 500 and 503 error body carries `hint`; a | |
| 144 | * site's own is kept. | |
| 145 | */ | |
| 119 | 146 | export function withHint(data: unknown, status: number): unknown { |
| 120 | 147 | if (HINTS[status] === undefined || typeof data !== "object" || data === null || Array.isArray(data)) return data; |
| 121 | 148 | const body = data as Record<string, unknown>; |
test/api-hints.test.ts +1 −1
| @@ -105,7 +105,7 @@ describe("refusals carry a hint", () => { | ||
| 105 | 105 | |
| 106 | 106 | test("a site's own hint is kept, and other statuses are left alone", () => { |
| 107 | 107 | expect((withHint({ error: "x", hint: "mine" }, 409) as { hint: string }).hint).toBe("mine"); |
| 108 | expect(withHint({ error: "x" }, 400)).toEqual({ error: "x" }); | |
| 108 | expect(withHint({ error: "x" }, 200)).toEqual({ error: "x" }); | |
| 109 | 109 | expect(withHint({ ok: true }, 404)).toEqual({ ok: true }); |
| 110 | 110 | }); |
| 111 | 111 | }); |
test/api-page-param.test.ts +3 −1
| @@ -66,7 +66,9 @@ for (const path of lists) { | ||
| 66 | 66 | for (const param of ["page=2", "offset=50"]) { |
| 67 | 67 | const res = await get(`${path}?limit=100&${param}`); |
| 68 | 68 | expect(res.status).toBe(400); |
| 69 | expect(await res.json()).toEqual(SAYS); | |
| 69 | const body = (await res.json()) as { hint?: string }; | |
| 70 | expect(body).toMatchObject(SAYS); | |
| 71 | expect(body.hint).toContain("?cursor="); | |
| 70 | 72 | } |
| 71 | 73 | expect((await get(`${path}?foo=1`)).status).toBe(200); |
| 72 | 74 | }); |
test/retry-after.test.ts +2
| @@ -35,6 +35,8 @@ const EXEMPT: Record<string, string> = { | ||
| 35 | 35 | [PERF_LINE]: "a comparison, not a response", |
| 36 | 36 | "src/http/respond.ts: if (status === 429 || status === 503) {": "json()'s floor itself", |
| 37 | 37 | "src/http/respond.ts: status: 429 | 503,": "tryAgain's own signature", |
| 38 | "src/http/respond.ts: 429: {": "a key of the error-hint table, not a response", | |
| 39 | "src/http/respond.ts: 503: {": "a key of the error-hint table, not a response", | |
| 38 | 40 | "src/http/api/print.ts: rate_limited: 429,": "status table; printRefusal answers through tryAgain", |
| 39 | 41 | "src/http/api/print.ts: daily_cap: 429,": "status table; printRefusal answers through tryAgain", |
| 40 | 42 | "src/http/api/conversation_talk.ts: return status === 429 || status === 503 ? tryAgain(said.error, status, words, talkWait(said.error)) : json({ error: said.error, message: words }, status);": |
new above
offline
HINTS still lacks 429 and 405, yet the Error schema requires
hintand every route declares 429. Add entries so tryAgain and methodNotAllowed bodies carry a hint.