docs field links to the matching section of this page.
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 unknownblockchain, 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. Addinstance=<client_id> to the request. The message lists your instances.
Authentication errors
missing_api_key
401. No API key was sent. Pass it asAuthorization: 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. Theinstance 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 theblockchain: 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 carriesRetry-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 therequest_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 andaccepted: false with this code.
duplicate
400. The user posted exactly the same text within the last day.sign_in_required
401. Browser API only: noAuthorization: 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 scopethesis. 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 ofhttps://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.
consent_required
403. Data API: the user has not signed in to your app with the scopethesis, 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 settingrequire_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 carriesRetry-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 thisexternal_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. Passwallets: [{"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 wasaccount_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 anotherexternal_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.
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 andcriteria 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 carrieslimit.
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 andlate_join is false, so it takes no new participants.
competition_full
409. The competition reachedmax_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 havewho: "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 (itswindow_ends_at). This rule applies whatever the settings.
callout_cooldown
429. The user made a callout less thancooldown_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 withtrading_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 atrader 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 asmanaged_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.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.
