Errors

Classification is on errors[].extensions.code and never on the HTTP status, because a 401-equivalent arrives inside an HTTP 200.

The gate and the fences

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

An operation that names no bot passes every fence. Most do: they address a flow, a contact or a conversation by an id that is not derivable from a bot id, and the auth gate page says what that means.

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 message and status; a 5xx is not, and becomes ProxyAuthUnavailable 503.

The recovery-link route

The admin panel

The publish queue

Answers with no code at all

Two, and both are deliberate.

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. The GraphQL route answers it for anything but POST, and the Node server's static half for anything but GET and HEAD.

The Vercel function answers 404 NotFound in envelope shape for a path under /chatfuel that the core does not claim. On the other two hosts an unclaimed path falls through to the host itself, which is what makes an unmounted route readable as "this deployment does not have that".

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 subscribe frame for a bot outside the fence is not a close at all. It comes back as an in-band error frame on that subscription's id, carrying AuthTenantForbidden or BotNotAllowed, 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 ChatfuelNetworkError, and ChatfuelHttpError with a 429 or a 5xx, up to three times with jittered backoff (1 s base, 30 s cap). 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 now 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" } }]
      }
    }
  ]
}

The proxy's own refusals use the same shape on every route, GraphQL or not, so one error path reads every answer — and they are sent cache-control: no-store, because a cached 403 would keep saying "not your bot" about a bot that has since become the caller's.

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