Errors & limits
Errors
Section titled “Errors”API errors return structured responses. Integrators should handle unauthorized, validation, and entitlement failures distinctly.
| HTTP | Code | When |
|---|---|---|
| 401 | MISSING_SESSION_TOKEN / MISSING_LICENSE_KEY |
Missing Bearer or license header |
| 403 | API_MODULE_DISABLED |
Public API module off for the deployment |
| 403 | ENTITLEMENT_LIMIT_EXCEEDED |
Plan quota exceeded (business code 803) |
| 400 | validation / maxFiles |
Bad request body or form field file cap |
| 502 | GRAPHQL_UNAVAILABLE / MEDIA_UNAVAILABLE |
Upstream GraphQL or media-service unreachable |
GraphQL-backed JSON routes map 803 to HTTP 403 with error.code = ENTITLEMENT_LIMIT_EXCEEDED. Media JSON responses that return business code: 803 (often with HTTP 200 upstream) are normalized the same way.
Gateway vs platform limits
Section titled “Gateway vs platform limits”| Layer | Enforced by | Examples |
|---|---|---|
| Gateway | RapidAPI (or successor) | Requests/month, gateway rate limits, billing |
| Platform | Kolony entitlements | Creates, invites, messaging, media uploads, memberships, form/workflow capacity, and related plan dimensions |
Both layers coexist. Exact platform caps depend on the caller’s role / plan and may change with packaging — use your RapidAPI (or account) plan details for numeric limits. When a platform cap is hit, expect ENTITLEMENT_LIMIT_EXCEEDED as above.
Separately, form configurations define per-field maxFiles (and related file metadata). That is a schema rule on the configuration you author, enforced on attachment upload — not a substitute for plan entitlements.
Versioning
Section titled “Versioning”The public REST contract is versioned under /v0. Kol-Api-Version reports the release semver (currently 0.0.8). Breaking changes will ship under a new major path prefix when required.