Errors
The Chatfuel API's error envelope — machine-readable codes in extensions, the DefinedErrorCode family, and the four rules that catch people.
Codes travel in extensions, and the HTTP status line is not where you look for them.
{
"errors": [
{
"message": "...",
"path": ["bot", "conversation"],
"extensions": { "code": "NotEnoughPermissions", "service": "livechat", "traceId": "..." }
}
]
}The rules that catch people
A 401-equivalent arrives inside an HTTP 200. The gateway answers 200 with an errors[] that
carries an Unauthorized code from a subgraph, so a client that branches on res.ok reads a
dead token as a successful request with no data. Scan errors[].extensions.code, always.
| Rule | What it means |
|---|---|
| A relayed subgraph failure hides the real code one level deeper. | The top-level message reads Failed to fetch from Subgraph 'x' and carries no useful code; the real entries — code, traceId — sit in extensions.errors[]. Every code lookup has to walk down one level too. workspaceCreateBot is one that answers this way: TooManyBotsInWorkspace and NotEnoughPermissions both arrive nested. |
data and errors can coexist. | Partial data is normal. The envelope is not "one or the other", so decide per view whether a partial render is acceptable rather than treating the presence of errors as the absence of data. |
| WhatsApp delivery failures are not GraphQL errors. | The send mutation succeeds. The failure appears later on the message itself, as Message.errors[] — a MessageError { code, date, originalErrCode, originalErrMessage } — and reaches you through the messageUpdated subscription. Nothing about it ever enters the error envelope. |
Where the codes come from
DefinedErrorCode is the schema's own "global enum for errors that must be handled on the
client". It has 285 values: three global ones and the rest per domain.
| Code | Meaning |
|---|---|
Unauthorized | The token is not valid any more. Rotate it; do not retry. |
NotEnoughPermissions | The role this token holds on this bot does not allow the operation — or the id is unknown, or belongs to somebody else. |
InternalServerError | The server failed. |
The rest are domain-specific — FileTooBig, FileContentTypeNotSupported, FileDoesNotExist,
TooManyBotsInWorkspace, EnabledTriggerIsImmutable, and so on. Which codes a given mutation can
return is written in that mutation's doc comment in the bundled schema, so the schema file is where
you look one up. The headings those lists appear under are not consistent — see
the traps.
The traceId
An error's extensions.traceId identifies the request inside Chatfuel, so include it when you
report a problem to them. It is subject to the nesting rule above: when the gateway relays a
subgraph failure, the traceId is on the nested entry, not the outer one.
This page is the API's half
Everything above is produced by Chatfuel. The SDK's own proxy and client produce a second family of codes — a missing session, a bot the caller has no grant for, an unreachable upstream — before a request ever reaches Chatfuel, or after its answer comes back. Those are on the errors reference.
Transport and auth
The three endpoints, how the Chatfuel token travels on each of them, what the token is and what it may do, how the WebSocket client behaves, and the rate limit.
Pagination
Relay cursors with a scalar and a PageInfo type per connection, the direction flip on message history, where first is required, and the connections that accept pagination arguments and ignore them.