Errors

Classification is on errors[].extensions.code and never on the HTTP status, because a 401-equivalent arrives inside an HTTP 200. Every refusal the proxy writes itself uses the same envelope shape as an answer from Chatfuel, on every route, and carries cache-control: no-store.

Before any route runs

Two checks stand in front of every route, and the WebSocket upgrade asks the same two. The values they read are on the proxy page; the reasoning is on the token boundary.

A refused upgrade gets plain HTTP 403 Forbidden before any socket exists.

The gate and the fences

These can answer any proxied route, before anything reaches Chatfuel.

An operation that names no bot and no resource passes every fence. The auth gate says what that means.

The ceilings

Every one of these is a value on the proxy page and a variable on environment variables.

What the proxy reads in a document

The GraphQL route and every subscribe frame on the socket run the same checks in the same order, and the first refusal is the one you get.

The sign-up and bot routes

Codes the database writes

The cf_* functions raise a machine code in PostgREST's hint, and the proxy maps it. A 4xx from the database is passed on with its own status and its own message; a 5xx is not, and becomes ProxyAuthUnavailable 503. A 4xx whose hint is not one of these was written by PostgREST itself — a constraint violation, a bad cast, a missing function — and its message would name tables and columns this deployment does not publish, so it is replaced with "That is not allowed".

The recovery-link route

The admin panel

The publish queue

Configuration problems, before any request

Four problems are recorded at startup, printed by name — never by value — and turn /chatfuel/healthz into {"ok":false} with a 503.

Answers with no code at all

A 405 carries an allow header and an empty body — no envelope, because a wrong method is a caller-side programming error and not an application answer. Every route answers it for a method it does not take, and the Node server's static half for anything but GET and HEAD.

WebSocket close codes

The relay's admission is the HTTP sequence's twin in close-code vocabulary — a change to one is a change to both.

Two more come from the client, not the proxy. graphql-ws closes with 4408 Request Timeout when a ping it sent goes unanswered for 5 s on top of the 10 s keepalive — a dead socket after about fifteen seconds. And a clean lazy idle close, 1000, is deliberately not treated as a lapse, so it triggers no refetch.

A refused subscribe is not a close at all. It comes back as an in-band error frame on that subscription's id, carrying the code the HTTP route would have answered with, so one bad subscription does not take the shared socket down with it.

shouldRetryWsError adds 4403 to what graphql-ws already hard-fails on (4400, 4401, 4406, 4409, 4429); everything else, network errors included, stays retryable with jittered backoff — 5 s base, 60 s cap, resolved early when the browser comes back online.

The api-client's error classes

Every class extends ChatfuelApiError, which extends Error. The names all carry the Chatfuel prefix.

toApiError decides in that order: session first, then auth, then plain GraphQL. The distinction between the last two is the one that matters — ChatfuelAuthError means the deployment's token is bad, ChatfuelSessionError means this person's sign-in is.

The throttle retries three times by default, with jittered backoff (1 s base, 30 s cap). A 429 is retried whatever the task was, because the server is saying it turned the request away before running it. A network failure or a 5xx is retried only for a task marked idempotent: the request may have reached Chatfuel, run, and lost its answer on the way back, and a retry there is a second execution — a wasted round trip for a query, a second workspace on somebody's card for a mutation. GraphQL and auth errors are never retried.

createClient's onSessionError fires once per lapse and re-arms on the next clean result. The shell wires it to the auth module, which treats two of those rejections as not a lapse: nobody is signed in (the topbar's bot-title query runs outside the gate, so a signed-out visitor always draws a 401), and a signed-in non-member on AuthTenantForbidden (the gate already shows /no-access, and signing them out would throw away the account they have only just made).

Helpers worth knowing: isSessionError(err), hasErrorCode(err, code), nestedErrorCodes(err) — which is duck-typed on .errors rather than instanceof, so a plain envelope-shaped object answers the same — and errorMessageFor(err, messages, fallback), which looks a code up in a table the caller owns.

The envelope

So every code lookup reads both levels, on both sides of the wire: errorCodes in the api-client and graphqlErrorCodes in the proxy. nestedErrorCodes puts the nested code first, because that is the one worth acting on.

An entry looks like this:

{
  "errors": [
    {
      "message": "…",
      "path": ["bot", "flows"],
      "extensions": {
        "code": "NotEnoughPermissions",
        "service": "bot",
        "traceId": "…",
        "errors": [{ "message": "…", "extensions": { "code": "Unauthorized" } }]
      }
    }
  ]
}

One code on that list is the proxy's own: an error entry naming an internal upstream service has that sentence replaced before it reaches the browser, and — when it carried no code of its own — is tagged UpstreamServiceError, so a caller classifies it by code rather than by matching a message.

Chatfuel's own codes — what Unauthorized and NotEnoughPermissions mean upstream, and the rest of that vocabulary — are on the API error reference.