Errors

Status-code glossary

4004xx

Malformed body, an unknown field, or a field that failed its own validation. The message names which. Choosing a client brand for a campaign link (brand_id) adds three codes: invalid_brand_id (not a UUID), brand_not_found (not one of your brands — the same answer whether it does not exist or belongs to another account) and brand_archived. Changing a brand (PATCH /api/v1/application-form/brands/{id}) adds brand_names_immutable (the body named a name field; create a new brand instead) and nothing_to_update; creating or changing one also returns the logo-rights, colour and name codes logo_rights_not_confirmed, invalid_colour, primary_colour_low_contrast, client_name_required, client_name_too_long, agency_name_required (the account has no company name; the agency of every brand is always that name), agency_name_too_long and invalid_multipart. Creating a brand with an agency_name field returns agency_name_not_settable. A logo change that loses a race with another one for the same brand returns 409 logo_changed_concurrently.

invalid_brand_idbrand_not_foundbrand_archivedbrand_names_immutablenothing_to_update

4014xx

Authentication failed — see Authentication. A missing, malformed, unknown, revoked or expired key is always this 401, never a 403.

4034xx

Your key is valid but the request was refused: the key was created Read only (every write; the body also carries code: "key_read_only"), your team role cannot write (every write — a viewer’s key, or an account that could not be read just then), your plan does not include ChurnGuard (every ChurnGuard endpoint), or a custom assistant name is not available (PATCH /settings/assistant). Tell them apart by the error string.

This API key is read-only. Create a full-access key to make changes.Your team role doesn't allow this. Ask your team's admin or owner.ChurnGuard is not included in your plan.A custom assistant name is not available on this account.

4024xx

A plan refusal. Creating a candidate: over your seat or message quota (the meta object carries the figures). Starting new outbound WhatsApp (template, start, restart, ChurnGuard send, and a manual reply when the plan has ended): the body carries code no_subscription (plan ended) or over_message_quota (this month’s messages used). Nothing was sent or written. A reply inside an open chat is never refused for the message limit.

5035xx

A read this request depends on could not be completed — retry. On a send endpoint, code: "billing_unavailable" means we could not check your plan; nothing was sent.

4044xx

Unknown id, someone else’s resource, or the whole API switched off for this deployment (an EMPTY body on that last case). Only ever the answer to a lookup that succeeded and found nothing — if our own read of the candidate fails you get a 503, never a 404.

Not found

4094xx

A conflict — creating a client brand when the account already holds the most it may (brand_limit_reached; archived brands count), a duplicate candidate, an in-flight Idempotency-Key, (the pack endpoint) documents not yet all accepted, or (publishing Candidate Match questions) a stale expected_version_no or a proposal identical to the live quiz.

4134xx

A client-brand logo upload is over the size cap (2 MB for PNG and JPEG, 512 KB for SVG). It is refused before the body is parsed.

logo_too_large

4154xx

A client-brand logo is not a PNG, JPEG or SVG, an SVG contains a refused construct (script, external reference, entity), or the file cannot be decoded.

unsupported_logounsafe_svgundecodable_logo

4224xx

A well-formed request refused for its content. Publishing Candidate Match questions: sensitive wording, either a blocked phrase or a warned phrase without acknowledge_sensitive: true. Nothing was written.

4294xx

Rate limit exceeded — see Rate limits. Respect the Retry-After header.

Too many requests — please try again shortly.

5005xx

The write could not be completed or verified. Safe to retry (with the same Idempotency-Key on a create).

5025xx

An upstream fetch (storage or Twilio media) failed. Safe to retry.

5035xx

The service, or a record a read depends on, is temporarily unavailable. Never a confident empty/negative payload — retry shortly.