> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cabalspy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Every error code of the CabalSpy ID Data API and trades stream, what it means and how to fix it.

Every Data API error has the same shape. The `docs` field links to the matching section of this page.

```json theme={null}
{
  "success": false,
  "error": {
    "code": "wallet_not_found",
    "message": "This wallet is not verified by a CabalSpy ID user in your instance (or beyond your plan's user limit)",
    "request_id": "req_5162c7cf7f87",
    "docs": "https://docs.cabalspy.xyz/cabalspy-id/errors#wallet_not_found"
  }
}
```

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](/cabalspy-id/openid-connect#oauth-errors).

## Overview

| Status | Code | Meaning |
| - | - | - |
| 400 | [missing\_parameter](#missing_parameter) | A required parameter is missing. |
| 400 | [invalid\_parameter](#invalid_parameter) | A parameter has an invalid value. |
| 400 | [instance\_required](#instance_required) | Your account has several instances, pass instance. |
| 401 | [missing\_api\_key](#missing_api_key) | No API key was sent. |
| 403 | [invalid\_api\_key](#invalid_api_key) | The API key is invalid or does not exist. |
| 403 | [product\_not\_enabled](#product_not_enabled) | The key is not enabled for CabalSpy ID. |
| 403 | [no\_instance](#no_instance) | Your account has no CabalSpy ID instance yet. |
| 403 | [scope\_not\_allowed](#scope_not_allowed) | scope=global needs the Enterprise plan. |
| 403 | [plan\_user\_limit](#plan_user_limit) | The user signed in beyond your plan's user limit. |
| 404 | [instance\_not\_found](#instance_not_found) | No instance with this client\_id in your account. |
| 404 | [profile\_not\_found](#profile_not_found) | No such user in your instance. |
| 404 | [wallet\_not\_found](#wallet_not_found) | The wallet is not verified by one of your users. |
| 429 | [rate\_limit\_exceeded](#rate_limit_exceeded) | Too many requests per second. |
| 500 | [internal\_error](#internal_error) | Something went wrong on our side. |
| 503 | [service\_unavailable](#service_unavailable) | A data source is temporarily unavailable. |
| 400 | [invalid\_body](#invalid_body) | Thesis or reply text rejected. |
| 400 | [duplicate](#duplicate) | The user already posted that text. |
| 401 | [sign\_in\_required](#sign_in_required) | Browser API: no user token sent. |
| 401 | [invalid\_token](#invalid_token) | Browser API: user token invalid or expired. |
| 403 | [scope\_missing](#scope_missing) | Browser API: the token lacks the scope thesis. |
| 403 | [consent\_required](#consent_required) | The user has not granted your app the scope thesis. |
| 403 | [sandbox\_user](#sandbox_user) | Sandbox test users cannot write theses. |
| 403 | [not\_a\_holder](#not_a_holder) | Only holders can post a thesis. |
| 403 | [posting\_paused](#posting_paused) | The user is paused from writing. |
| 403 | [reporting\_paused](#reporting_paused) | The user cannot report for now. |
| 404 | [not\_found](#not_found) | The thesis or reply is not available. |
| 429 | [rate\_limited](#rate_limited) | The user writes too fast. |
| stream | [plan\_required](#plan_required) | The stream needs the Pro plan or higher. |
| stream | [too\_many\_tokens](#too_many_tokens) | Theses stream: more than 200 tokens on one connection. |
| stream | [invalid\_frame](#invalid_frame) | Theses stream: a frame was not understood. |
| stream | [too\_many\_connections](#too_many_connections) | At most 5 stream connections per key. |

## Request errors

### missing\_parameter

**400.** A required parameter is missing. `parameter` names it. On [Profile](/cabalspy-id/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](/cabalspy-id/data-api#authentication).

### invalid\_api\_key

**403.** The API key is invalid, revoked or does not exist. Copy the key again from the [API Dashboard](https://apidashboard.cabalspy.xyz). 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](/cabalspy-id/plans#the-user-limit).

### 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.

## 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](/cabalspy-id/plans#rate-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, currently used by [Holdings](/cabalspy-id/holdings). Retry shortly.

## Thesis errors

These codes come from the [thesis](/cabalspy-id/theses) endpoints of the Data API and from the [browser API](/cabalspy-id/theses-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.

### 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.

### consent\_required

**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](/cabalspy-id/theses-eligibility) returns this as `reason` instead of an error.

### 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.

### 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](/cabalspy-id/theses-moderation#reports).

### 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.

### 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. Different from rate\_limit\_exceeded, which is about your API key.

## Stream errors

The [trades stream](/cabalspy-id/stream) sends errors as a message and then closes the connection with code 4403.

```json theme={null}
{ "event": "error", "error": { "code": "too_many_connections", "message": "At most 5 stream connections per API key." } }
```

It can also send invalid\_api\_key, invalid\_parameter (blockchain, events or mint), missing\_parameter (mint without blockchain) and scope\_not\_allowed, described above.

### plan\_required

The live stream is included from the Pro plan. Upgrade at [apidashboard.cabalspy.xyz/billing/csid](https://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](/cabalspy-id/theses-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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.