Skip to main content
Every Data API error has the same shape. The docs field links to the matching section of this page.
Parameter errors add parameter, the parameter at fault, and where it helps allowed, the accepted values. Always quote the request_id when you contact support. Errors of the OpenID Connect endpoints use the OAuth format instead, see OAuth errors.

Overview

Request errors

missing_parameter

400. A required parameter is missing. parameter names it. On Profile it means you did not pass exactly one of username, csid_id or address.

invalid_parameter

400. A parameter has an invalid value, for example an unknown blockchain, a period other than 6h, 1d, 7d or 30d, a limit out of range, an unknown sort, a malformed cursor or a csid_id that is not the sub of a CabalSpy ID token. parameter names it and allowed lists the accepted values where there is a fixed list. On the stream it means an invalid blockchain.

instance_required

400. Your account has several CabalSpy ID instances and the API cannot tell which one you mean. Add instance=<client_id> to the request. The message lists your instances.

Authentication errors

missing_api_key

401. No API key was sent. Pass it as Authorization: Bearer <key> or as the apiKey or api_key query parameter. See Authentication.

invalid_api_key

403. The API key is invalid, revoked or does not exist. Copy the key again from the API Dashboard. On the stream this code is also used when no key was sent.

product_not_enabled

403. The key is valid for the CabalSpy API but not enabled for CabalSpy ID. Open the API keys page of the dashboard and switch on CabalSpy ID for the key.

no_instance

403. Your account has no CabalSpy ID instance yet. Create one in the dashboard on the CabalSpy ID tab.

instance_not_found

404. The instance you passed is not an active CabalSpy ID instance of your account. Check the Instance ID (csid_...) in the dashboard.

Access errors

scope_not_allowed

403. scope=global, access to every CabalSpy ID user, is available on the Enterprise plan. Without it your key sees the users of your instance. Remove the parameter or contact sales.

plan_user_limit

403. You passed an anonymous id (anon_...). The person signed in beyond your plan’s user limit, so your platform receives no data for them until it upgrades. The error carries "limited": true. See Plans and limits. White-Label: a new platform user does not fit in your plan. All seats of your domain’s plan are taken, or a sandbox or development instance already holds 25 platform users. The error carries user_limit, and on live instances users and plan. Existing users can still be updated. Starting a wallet verification for a user without a seat returns it too.

profile_not_found

404. No CabalSpy ID user matches the username, csid_id or address, or the user is not visible to your key: they never signed in to your instance, removed access, were blocked by you, or are beyond your plan’s user limit.

wallet_not_found

404. The wallet is not verified on this chain by one of your users. Check the blockchain: a wallet is only found on the chains it is verified on, listed in the user’s wallets[].chains. As with profile_not_found, users outside your instance or beyond your plan’s user limit are not visible. White-Label: on Remove a wallet, the platform user has no wallet with this address.

Limits

rate_limit_exceeded

429. You sent more requests per second than your plan allows. The response carries Retry-After: 1, wait a second and retry. X-RateLimit-Limit shows your limit. See Plans and limits.

Server errors

internal_error

500. Something went wrong on our side. Retry with a backoff, and contact support with the request_id if it persists.

service_unavailable

503. A data source is temporarily unavailable, used by Holdings, and by wallet verification and Telegram linking for platform users. Retry shortly.

Thesis errors

These codes come from the thesis endpoints of the Data API and from the browser API. Their messages are written for end users, so you can show them as they are. plan_user_limit (above) also applies when a user beyond your plan’s user limit tries to write.

invalid_body

400. The text was rejected: empty, longer than 1,000 characters, more than two links, written in all caps, repeated-character spam, or containing a blocked word. The message says which. On the inbound URL: the body is not JSON. A JSON body that is not an object is answered with 200 and accepted: false with this code.

duplicate

400. The user posted exactly the same text within the last day.

sign_in_required

401. Browser API only: no Authorization: Bearer <token> was sent. Let the user sign in with CabalSpy ID and pass their access token.

invalid_token

401. Browser API only: the user’s token is invalid or expired, the user revoked access, or the account is not active. Access tokens live 15 minutes, refresh the token or let the user sign in again.

scope_missing

403. Browser API only: the access token does not carry the scope thesis. Request thesis at sign-in. The Trade Feed widgets and their browser API need the scope trade_feed instead.

client_id_required

401. Browser API only: the request carried no client_id. Every call of https://id.cabalspy.xyz/thesis/v1 needs your instance’s public client_id, as header X-CSID-Client-Id: csid_... or query ?client_id=csid_...; the websocket takes ?client_id=. For the widget set data-client-id on the data-csid-thesis element. The SDK’s ThesisClient needs clientId (TypeScript) or client_id (Python) from version 0.5.2. The client_id is shown in the API Dashboard under CabalSpy ID, Instances next to the API key. It is public, not the API key. On the websocket the connection closes with code 4401 and reason client_id_required. See Client ID.

invalid_client

401. Browser API only: the client_id is not an active instance: it is unknown, suspended or deleted. Also returned when the header and the query parameter carry different client_ids. Copy the Instance ID (csid_...) again from the dashboard. On the websocket the connection closes with code 4401 and reason invalid_client.

origin_not_allowed

403. Browser API only: the request came from a page that is not one of your instance’s sites. Allowed are the registered allowed origins, the origins of your redirect URIs and your verified domain including its subdomains (https), and, while the instance is not in live mode, http://localhost:* and http://127.0.0.1:*. Add the origin in the dashboard or verify the domain. Calls from a server without an Origin or Referer header only need a valid client_id. The /embed/thesis iframe of the widget can likewise only be framed by these sites. On the websocket the connection closes with code 4403 and reason origin_not_allowed. 403. Data API: the user has not signed in to your app with the scope thesis, revoked it, or is blocked by you. Ask the user to sign in again with the scope. Eligibility returns this as reason instead of an error. Trade Feed and copy trading endpoints answer with this code when the user has not signed in to your app with the scope trade_feed, revoked it, is blocked by you, or is beyond your plan’s user limit. Request trade_feed at sign-in. Platform users always have the scope.

sandbox_user

403. Made-up sandbox test users cannot write theses.

not_a_holder

403. Only holders can post a thesis: one of the user’s verified wallets must have bought the token and still hold it. Replies, reactions and reports do not need this. Callouts: with the setting require_holding (on by default), the user must hold the token in one of their wallets that count on its chain. Switch it off in the callout settings to let anyone call.

posting_paused

403. The user is paused from posting, replying and reacting, for example after several of their posts were hidden after reports. The message says until when.

reporting_paused

403. Moderators rejected too many of the user’s reports, so they cannot report posts for 30 days. The message says until when. See Moderation and appeals.

not_found

404. For appeals: there is no such notification for this user, or it cannot be appealed. Otherwise: the thesis or reply does not exist, was hidden or deleted, or the user tried to delete someone else’s post. Replies to a reply are also refused with this code. Copy trading: there is no copy instruction with this id for your instance. Instructions of users copied by another platform are not visible to you.

rate_limited

429. The user writes too fast: 5 theses per hour and 1 per token every 10 minutes, 30 replies per hour, 120 reactions per hour, 20 reports per day. On the browser API also too many requests from one IP address or for one client_id: about 600 reads and 300 writes per minute per client_id, 120 reads per minute per IP address, and the per-IP write limits of the browser API. The response carries Retry-After: 60. On the websocket the connection closes with code 4429 and reason rate_limited. Different from rate_limit_exceeded, which is about your API key. Trade Feed: more than 120 changes to one user’s Trade Feed per hour, including copy settings changes. Try again later. White-Label: more than 2,000 new platform users per minute, more than 600 events per minute on the inbound URL, or wallet verifications started too fast. These answers carry a Retry-After header with the seconds until the next full minute.

White-Label errors

These codes come from the White-Label endpoints under /v1/platform-users and from other endpoints when you pass external_id.

platform_user_not_found

404. No platform user with this external_id (or csid_id) in your instance. Create it with POST /v1/platform-users first. Every endpoint that takes external_id in place of csid_id answers with this code too.

wallet_required

400. A new platform user needs at least one wallet. Pass wallets: [{"address": "..."}]. Also returned by Add wallets without wallets.

invalid_address

400. A wallet is not a valid Solana or EVM address, or, for a verification, the address does not match the chain. wallets[i] in the message names the item.

too_many_wallets

409. The user would have more than 5 Solana or more than 5 EVM wallets. Remove one first.

last_wallet

409. Every platform user needs at least one wallet, so the last one cannot be removed. Add another wallet first, or delete the user.

self_managed

409. The person signs in to their CabalSpy ID themselves and manages profile, X and Telegram. You can still read their data, report wallets and delete your link, but not change the account. Until 0.10.0 of the SDKs this code was account_claimed.

already_linked

Not an HTTP error. A person is your user only once: when one of your users proves an identity (X, Telegram or a paid wallet) of a CabalSpy ID that is already your user under another external_id, nothing is merged. What you see depends on the flow:
  • X: the return URL gets error=x_already_linked.
  • Telegram: the bot tells the person, and the Telegram stays unlinked.
  • Wallet verification: the payment is not matched; the verification expires (verification.expired). Contact support if a user paid.
Remove one of the two users first.

wallet_already_verified

409. Another account already verified this wallet with a payment. It cannot be verified again.

already_verified

409. The wallet is already verified on this chain.

too_many_open_verifications

429. Too many wallet verifications are open at once. Wait until one is paid or expires, or cancel one.

verification_not_found

404. No wallet verification with this id for your platform users.

claim_removed

410. Claim links are gone. Every person has one CabalSpy ID: your user moves to their own ID by itself when they prove it, see One person, one CabalSpy ID.

invalid_return_url

400. return_url must be on one of your instance’s verified domains (or a subdomain), registered origins or redirect URIs, over https, or on http://localhost.

kol_badge

409. The user has the KOL badge, which belongs to their X account, so X cannot be disconnected.

x_required

409. The KOL badge needs a connected X account. Connect it with X connect first.

kol_not_eligible

409. The KOL application was refused. The message says why and criteria lists the badge criteria. See KOL badge.

volume_check_unavailable

409. A volume check cannot be requested right now. The message says why; volume_check_next_at in the KOL status says when the next one is possible.

invalid_inbound_url

404. The inbound URL is unknown, was replaced by a newer one, or is disabled. Enable it again to get a new URL.

Competition errors

These codes come from the competition endpoints.

competition_not_found

404. No competition with this id in your instance.

competition_limit

409. At most 5 competitions can be open at the same time (scheduled, waiting and running) per developer account, across all your instances. End or cancel one first. The error carries limit.

competition_closed

409. The competition already ended or was cancelled. It can no longer be changed, joined or left.

late_join_closed

409. The competition is running and late_join is false, so it takes no new participants.

competition_full

409. The competition reached max_participants.

Callout errors

These codes come from the callout endpoints and from creating or updating a callout competition. Their messages are written for end users, so you can show them as they are. Callouts also use not_a_holder, posting_paused, consent_required, sandbox_user, plan_user_limit, platform_user_not_found and service_unavailable (the price could not be read).

feature_not_enabled

403. Callouts are switched on per instance on request, and they are not on for yours. Every callout endpoint, the callouts stream, creating a competition with "kind": "callouts" and updating an existing callout competition answer with this code. Contact us at contact@cabalspy.xyz to enable them. GET /v1/me lists "callouts" in features once they are on.

invalid_account

403. The user’s account is not active, so they cannot make callouts.

kol_only

403. Your callout settings have who: "kol_only", and the user does not have the KOL badge. See KOL badge.

already_called

409. The user called this token less than 24 hours ago. A user can call the same token once per 24 hours; a new callout is possible once the first day of the previous one is over (its window_ends_at). This rule applies whatever the settings.

callout_cooldown

429. The user made a callout less than cooldown_minutes ago (6 hours by default, see callout settings). The response carries a Retry-After header and retry_after in the error, both the seconds until the user can call again. Different from rate_limit_exceeded, which is about your API key.

no_price

422. The token has no market price yet, for example because it has not traded, so a callout could not be tracked. Try again once it trades.

callout_not_found

404. No callout with this id in your instance, or it was removed. Removing a callout that is already removed answers with this code too.

Trade Feed errors

These codes come from the Trade Feed endpoints, the Trade Feed widgets and from copy settings, which add the trader to the Trade Feed when needed. Their messages are written for end users, so you can show them as they are. The Trade Feed also uses consent_required, plan_user_limit, platform_user_not_found and rate_limited.

trader_not_found

404. No active CabalSpy ID trader with this handle or csid_id. Platform users of another platform can only be found when that platform switched on network sharing.

cannot_add_self

400. The user tried to add themselves to their own Trade Feed, or to copy themselves.

trading_private

403. The trader keeps their trading private, so they cannot be added to a Trade Feed or copied. Traders already in a Trade Feed who switch to private stay listed with trading_public: false, but nothing of them shows until they are public again.

trade_feed_full

409. The user’s Trade Feed already has the maximum of 300 traders. Remove one first with POST /v1/trade-feed/traders/delete.

Copy trading errors

These codes come from the copy trading endpoints. Copy trading also uses consent_required, platform_user_not_found, not_found and the Trade Feed errors.

not_in_trade_feed

404. GET /v1/copy-trading/settings with a trader who is not in the user’s Trade Feed, so there are no copy settings for them. POST /v1/copy-trading/settings adds the trader automatically.

copy_managed_elsewhere

409. Another platform copies this trader for this user, and each trader is copied by one platform at a time so the user is never copied twice. The user has to switch copying of this trader off on the other platform first. GET /v1/copy-trading/settings shows this as managed_by_other_platform: true. See One platform at a time.

already_reported

409. The copy instruction was already reported with a different final status (executed, failed or skipped), and a final status cannot change. The message names the current status. Sending the same status again is not an error. See Report the result.

Stream errors

The trades stream sends errors as a message and then closes the connection with code 4403.
It can also send invalid_api_key, invalid_parameter (blockchain, events or mint), missing_parameter (mint without blockchain) and scope_not_allowed, described above. The callouts stream sends errors the same way, with invalid_api_key, feature_not_enabled, invalid_parameter (chain or mint), missing_parameter (mint without chain) and too_many_connections. The Trade Feed stream and the copy trading stream send invalid_api_key and too_many_connections.

plan_required

The live stream is included from the Pro plan. Upgrade at apidashboard.cabalspy.xyz/billing/csid.

too_many_connections

Each API key can hold at most 5 stream connections at once, and separately 5 theses stream, 5 callouts stream, 5 Trade Feed stream and 5 copy trading stream connections. Close unused connections, or share one connection across your services.

too_many_tokens

Theses stream only: a subscribe frame would take the connection above 200 tokens. The frame is ignored and the connection stays open. Unsubscribe from tokens you no longer show, subscribe with "all": true, or open another connection.

invalid_frame

Theses stream only: the frame is not JSON or not a known op. Send {"op": "subscribe", "tokens": [{"blockchain": "solana", "mint": "..."}]}, {"op": "unsubscribe", ...}, {"op": "subscribe", "all": true} or ping. The connection stays open.