Errors

This page is generated from the error helpers in packages/engine, packages/auth and apps/server by pnpm generate. Do not edit it by hand; change the source and regenerate.

Every failure is the same envelope, with the HTTP status that matches the code:

{
  "success": false,
  "error": { "code": "ALREADY_IN_SEQUENCE", "message": "2 of the 142 contacts are already in a sequence. Nobody was enrolled. Remove them from the selection or exit them from their current sequence first.", "details": { "conflicts": [] } },
  "meta": { "request_id": "req_k3…" }
}

Messages are plain English and may change; code is stable, so branch on it. details is structured when there is something to act on (the conflicts of ALREADY_IN_SEQUENCE, the problems of INVALID_DEFINITION, the missing scopes of SCOPES_MISSING). The TypeScript SDK throws OpenSequenceError with status, code, message, details and requestId.

HTTP error codes

Code	HTTP	Message	What to do
`ALREADY_IN_SEQUENCE`	409	… of the … contacts are already in a sequence. Nobody was enrolled. Remove them from the selection or exit them from their current sequence first.	Remove the listed contacts (`details.conflicts`) from the selection, or exit them first with `POST /v1/enrollments/\{id\}/exit`. Nobody was enrolled.
`BAD_FLAG`	422	A flag is "global" or "channel:<name>".
`BAD_OUTCOME`	422	Give the outcome of the task, like "connected" or "no_answer".
`BAD_SCOPE`	422	Unknown scope: …. Use read, enroll or admin.
`BAD_TAG`	422	A tag is up to 24 letters, digits, dots and dashes, like v2.
`BATCH_TOO_LARGE`	422	At most … contacts per call.
`CREDENTIAL_INVALID`	409	The … credential was marked invalid by a health check. Register a new one.
`ENDPOINT_DISABLED`	409	Enable the endpoint first; it is disabled.
`HAS_ACTIVE_ENROLLMENTS`	409	… contacts are still in this sequence. Exit them first, or send exit_active: true.	Exit them first, or send `exit_active: true` to exit them with reason `manual`.
`INSUFFICIENT_SCOPE`	403	This key cannot do that; it needs the "…" scope.	Use a key with the scope the route needs (`read` < `enroll` < `admin`).
`INTERNAL_ERROR`	500	Something went wrong on our side. Reference ….
`INVALID_DEFINITION`	422	The definition has errors; fix them before publishing. `details.problems` lists them.	Fix every problem in `details.problems` (each has a `path`, a `code` and a sentence) and publish again. Saving a draft with errors is allowed; publishing is not.
`INVALID_EVENT`	422	The event is not valid: …
`INVALID_SLUG`	422	A slug is 3 to 48 lowercase letters, digits and dashes.
`INVALID_STATE`	400	The OAuth state is malformed, its signature does not match, or it belongs to another connection. Start the connection again.
`MISSING_SECRET`	422	An oauth2 credential needs client_id and client_secret.
`NO_ACCOUNT`	422	Google did not say which account consented. Connect again and allow the email permission.
`NO_CONTACTS`	422	Give at least one contact.
`NO_PUBLISHED_VERSION`	409	This sequence has no published version yet.	Publish a version before enrolling.
`NO_REFRESH_TOKEN`	422	Google returned no refresh token. Connect again; the consent screen must be shown.
`NOT_ACTIVE`	409	This enrollment is … (only active and waiting_limit enrollments can be paused).
`NOT_FOUND`	404	… "…" was not found. (Also: no route for this method and path.)
`NOT_PAUSED`	409	This enrollment is … (only paused and waiting_limit enrollments can be resumed).
`NUMBER_HAS_NO_SMS`	422	… cannot send SMS.
`PROVIDER_NOT_CONFIGURED`	409	No Google OAuth client is registered for this tenant. Register one (client_id, client_secret) first.
`REQUEST_ERROR`	400, 413, 429	A request-level error with its own message: malformed JSON (400), a body over 2 MB (413), or "Rate limit exceeded, retry in …" (429, 600 requests per minute per key, with a `Retry-After` header).
`SCOPES_MISSING`	422	Google did not grant the Gmail permissions this connection needs. Connect again and allow every box.
`SENDER_DISABLED`	409	… is disabled.
`SEQUENCE_NOT_ACTIVE`	409	The sequence is ….
`SLUG_TAKEN`	409	The slug "…" is already used.
`STALE_LOCK`	409	Someone else saved this draft after you loaded it. Reload and try again.	Reload the version, re-apply your change on the new `lock_version`, save again.
`STATE_EXPIRED`	400	The OAuth state expired (it lasts ten minutes). Start the connection again.
`TAG_TAKEN`	409	Version … already exists.
`UNAUTHORIZED`	401	Send a project API key as a Bearer token. / This API key is unknown or revoked. / This endpoint needs the operator token.	Send `Authorization: Bearer \<key\>`; the key must exist and not be revoked. `/v1/admin/*` wants the operator token instead.
`UNKNOWN_CHANNEL`	422	"…" is not a channel.
`UNKNOWN_EVENT_TYPE`	422	Unknown event type: …. Use "*" or one of ….	Use `"*"` or the types listed by `GET /v1/schema/events`.
`UNKNOWN_NUMBER`	422	… is not a number the Allo key can see.
`UNSAFE_URL`	422	The endpoint URL ….	Endpoint URLs must be `https`, carry no credentials, and resolve to a public address.
`VALIDATION_ERROR`	400	The request did not match the schema. `details` lists each path and message.
`VERSION_NOT_EDITABLE`	409	Version … is … and cannot be edited. Create a new version from it. (Also: only drafts can be deleted.)	Published and archived versions are frozen. Create a new draft from it: `POST /v1/sequences/\{id\}/versions` with `from_version`.
`VERSION_NOT_PUBLISHED`	409	Version … is …; only a published version can enroll.

Validation problems

Returned by POST /v1/sequences:validate, PUT .../draft (as problems, saving is allowed) and POST .../publish (inside a 422 INVALID_DEFINITION). Each problem is { path, code, message, severity }. See Validation for the fix of each one.

Code	Severity	Example message
`BAD_EVENT`	error	The event "…" is waited for but has no next step.
`BAD_OPERATOR`	error	"…" cannot be used on … (…). Use one of: ….
`BAD_TEMPLATE`	error	"{{ … }}" is not something a template can read. Use contact., attrs., sender.*, sequence.name or unsubscribe_url.
`BAD_VALUE`	error	"…" needs a value.
`CYCLE`	error	Steps … loop without a wait in between; the contact would never leave them.
`INVALID_DEFINITION`	error	The definition is … KB; the limit is … KB.
`MISSING_TRANSITION`	error	A … step must say where "…" goes.
`NO_UNSUBSCRIBE`	warning	This email has no {{ unsubscribe_url }}. Recipients cannot opt out with one click.
`TOO_LONG`	warning	The SMS is … characters (… segments).
`TOO_MANY_SMS`	error	A sequence can send at most one text; this one has ….
`UNKNOWN_ACTION`	error	"…" is not an action of …. Available: ….
`UNKNOWN_CHANNEL`	error	An outreach step needs a channel.
`UNKNOWN_FIELD`	error	"…" is not a field conditions can read.
`UNKNOWN_NODE`	error	The entry node "…" does not exist.
`UNKNOWN_NODE_TYPE`	error	"…" is not a node type. Available: ….
`UNREACHABLE_NODE`	error	"…" can never be reached from the entry step.

HTTP error codesCopy Anchor Link

Validation problemsCopy Anchor Link

On this page

HTTP error codes

Validation problems