Response envelope#
Success puts the resource under data (and pagination under meta); failure puts a stable code under error.
// success
{ "data": <resource | resource[]>,
"meta": { "pagination": { "cursor": "abc", "hasMore": true, "truncated": false } } }
// error
{ "error": { "code": "session_unavailable", "message": "…", "status": 401 } }
Error codes#
| Code | HTTP | When |
|---|---|---|
| unauthorized | 401 | API key missing, invalid or expired. |
| session_unavailable | 401 | The Skool connection expired or is missing. Reconnect the account. |
| forbidden | 403 | The API key lacks the scope this route requires, or X-Skool-Connection names a connection the key is not bound to. |
| invalid_request | 400 | Bad input: missing ?group=, invalid JSON body, empty title/content, unknown label (the message lists the group's labels). |
| not_found | 404 | Group not cached for this connection, or the post/comment does not exist (or was already deleted). |
| payment_required | 402 | No active subscription or trial on the account. Start or reactivate the plan at myskool.xyz/billing. |
| rate_limited | 429 | 60 req/min per key exceeded. See Retry-After. |
| quota_exceeded | 429 | Monthly quota (30,000 requests) used up. Resets on the 1st of the month (UTC). No Retry-After. |
| connection_limit | 409 | The plan's 3 Skool connections are in use. Delete one to connect another (management API). |
| skool_bad_request | 400/403/404 | Skool returned a hard 4xx (passthrough). |
| skool_upstream_error | 502 | Skool failed (5xx/429) after retries. |
| skool_shape_changed | 502 | Skool's response shape changed (unrecognizable payload). |