HttpFailure

@forge/monorepo

---

@forge/monorepo / backend/src / HttpFailure

Type Alias: HttpFailure

HttpFailure = object

Defined in: backend/src/toolkit/http.ts:65

Why a request did not happen, or did not produce a body worth reading.

A reason, not an exception. A refused URL is information the model can act on — try a different one, or tell the person why it cannot — while a thrown error reads as "something broke", and the usual response to that is to retry the identical call. kind is there so a caller can branch without matching on prose.

Properties

headers?

readonly optional headers?: Readonly<Record<string, string>>

Defined in: backend/src/toolkit/http.ts:91

The vendor's rate-limit headers, and only those — see RATE_LIMIT_HEADERS.

An allowlist rather than every header, for two reasons. A failure travels into error messages and audit records, so carrying set-cookie or an auth echo would be a leak with no purpose. And a bounded set says what this field is for: retryAfterMs answers "how long", and these answer the question X forces — which limit was hit. A 15-minute burst limit and a 24-hour cap are both 429, and treating the second as retryable makes a client sit in backoff until tomorrow.

---

kind

readonly kind: "forbidden" | "redirected" | "timeout" | "unreachable" | "http-error" | "unreadable"

Defined in: backend/src/toolkit/http.ts:68

---

ok

readonly ok: false

Defined in: backend/src/toolkit/http.ts:66

---

reason

readonly reason: string

Defined in: backend/src/toolkit/http.ts:70

---

retryAfterMs?

readonly optional retryAfterMs?: number

Defined in: backend/src/toolkit/http.ts:81

Retry-After, in milliseconds, when the server sent one.

Parsed here because it is the one response header a failure still needs to carry: a vendor that answers 429 with Retry-After: 47 has told you exactly how long to wait, and a default backoff that ignores it either hammers the vendor or waits far too long. PlatformError.retryAfterMs already exists and the retry path already reads it — this is the missing link between them.

Both wire formats: a delay in seconds, and an HTTP date.

---

status?

readonly optional status?: number

Defined in: backend/src/toolkit/http.ts:69

---

url

readonly url: string

Defined in: backend/src/toolkit/http.ts:67