Errors

The error envelope and the stable error codes, with what each one means and what to do.

All errors look the same.

{
  "error": {
    "code": "not_found",
    "message": "Mention not found",
    "requestId": "4b0e7d21-9c3a-4f62-8d15-7e2a0c9b6f13"
  }
}

Handle errors by code. Codes don't change, but new ones can appear, so treat an unknown code like any error with its status.
message is for people and can change. For validation_error it names the field ("term: Required").
requestId equals the X-Request-Id header. Include it when you contact support.

Retrying

Retry 5xx, 408 and 429 after the wait the response gives. Every 429 rate_limited has Retry-After and retryAfterSeconds.
Don't retry 503 database_not_ready. The deployment needs maintenance.
Other 4xx codes mean the request must change. 409 classification_pending clears once the mention is scored.

Codes

Credentials and access

Code	Status	Meaning
`unauthorized`	401	Missing, unknown, revoked or expired credential. Send `Authorization: Bearer ref_…` with a key from the API keys page.
`read_only_key`	403	A `read` credential tried to write. Use a `write` key.
`forbidden`	403	Not allowed for this credential or role, such as an API key changing the team or anyone changing an owner's role
`key_limit`	409	The workspace has 100 keys that aren't revoked

Requests

Code	Status	Meaning
`validation_error`	400	A field or parameter is missing or wrong. The message names it.
`not_found`	404	No such resource in your workspace, or no such route. Also a cursor whose item is gone.
`invalid_cursor`	400	The cursor can't be read or belongs to another sort
`unsupported_media_type`	415	The body isn't `application/json`
`payload_too_large`	413	The body is over 128 KiB
`request_timeout`	408	The body took over 5 seconds
`rate_limited`	429	Over the workspace or endpoint limit (Rate limits)
`conflict`	409	The change clashes with existing data
`request_conflict`	409	A `requestId` reused with a different body
`stale_version`	409	The resource changed since you read it (`ifVersion`)

Keywords, groups and billing

Code	Status	Meaning
`duplicate_keyword`	409	This group already has that term
`insufficient_balance`	402	The balance can't pay another keyword-day. Top up.
`keyword_limit_reached`	402	The 500-keyword limit is reached
`duplicate_group`	409	A group with that name or `externalId` exists
`default_group`	409	The default group can't be deleted
`default_group_context`	400	The default group has no description of its own. Use `PATCH /v1/company`.
`billing_not_configured`	503	Top-ups and invoices aren't available here
`no_billing_owner`	404	The workspace has no owner to bill

Mentions, views, segments and the team

Code	Status	Meaning
`invalid_assignee`	400	The assignee isn't in the workspace
`classification_pending`	409	A verdict for a mention that isn't scored yet
`already_classified`	409	A rescore for a mention that is already scored
`keyword_inactive`	409	A rescore for a mention whose keyword is muted
`duplicate_view`	409	A view with that name exists (case ignored)
`duplicate_segment`	409	A segment with that name exists
`already_member`	409	The invited address is already a member
`last_owner`	409	The last owner can't be removed

Alerts and channels

Code	Status	Meaning
`unknown_channel`	400	The rule names a channel outside the workspace
`not_a_digest`	400	`run` on an instant rule
`hourly_email_unsupported`	400	Hourly rules can't send email
`rule_disabled`, `no_channels`	409	The rule is off or has no channel. Only from test and run endpoints outside the reference.
`channel_disabled`	409	The channel is off
`slack_not_connected`	409	Slack isn't connected (404 on the Slack connection endpoints)
`slack_not_configured`, `telegram_not_configured`, `email_not_configured`	503	That channel type isn't set up here
`delivery_not_configured`, `delivery_key_unavailable`	503	Stored channel secrets can't be used here
`no_recipients`	409	The email channel has no recipients
`recipient_suppressed`	409	The address bounced or reported spam
`confirmation_rate_limited`	429	Too many confirmation emails to this address
`version_conflict`	409	The webhook's preset rules changed at the same time. Read it again.
`invalid_signature`	401	An incoming Slack or Telegram request wasn't signed correctly
`invalid_token`	400	An email link was changed, is malformed or expired (404 for invitation links)

Delivery log

Code	Status	Meaning
`not_retryable`	409	Only failed or held deliveries can be retried
`not_replayable`	409	Only finished deliveries can be replayed
`digest_retry_expired`	409	The retry window is over (6 hours, or 45 minutes past the hour for hourly digests)
`digest_has_replay`	409	There is a newer replay of this digest
`payload_too_large`	409	The payload is over 1 MiB and can't be sent
`email_hourly_limit`	409	Retrying an email held by the channel's 20-an-hour limit. It waits for a daily digest rule on the channel.
`email_idempotency_expired`	409	The safe retry window passed. A replay may send the email twice.
`confirmation_requires_resend`	409	Confirmation emails are resent, not retried
`delivery_request_incomplete`	500	A test's saved result couldn't be read. Read it again.

A test email over the limit of 5 an hour, or an instant email over 20 an hour, is not an HTTP error. The request returns 200 and the delivery shows email_test_rate_limited or email_hourly_limit.

Upstream and service

Code	Status	Meaning
`upstream_unavailable`	502	A provider such as payments or Slack didn't respond. Retry with backoff.
`source_unavailable`	502, 503	A platform didn't respond to a live search
`source_timeout`	504	A platform was too slow on a live search
`email_transport_unavailable`	503	Email sending isn't set up for this delivery
`invalid_host`, `invalid_origin`	403	An MCP request from a host or origin that isn't allowed
`database_unavailable`	503	A short database problem. Retry.
`database_not_ready`	503	The deployment needs maintenance
`not_configured`	503	No database is configured
`internal_error`	500	Something failed on our side. Retry, and send the `requestId` if it persists.

The OpenAPI document lists each operation's codes. The MCP server returns the same codes as a tool error, { "error": { "code", "message", "requestId" } }.

Errors

RetryingCopy Anchor Link

CodesCopy Anchor Link

Credentials and accessCopy Anchor Link

RequestsCopy Anchor Link

Keywords, groups and billingCopy Anchor Link

Mentions, views, segments and the teamCopy Anchor Link

Alerts and channelsCopy Anchor Link

Delivery logCopy Anchor Link

Upstream and serviceCopy Anchor Link

On this page