Errors

Every error is JSON:

{ "error": "This tier is sold out", "code": "TIER_FULL" }

error is a human-readable message. Do not branch on it; it can change.
code is the machine-readable code, where the endpoint documents one. Branch on it.
Some errors carry extra detail fields, for example missingFields, remaining, hint, alternatives or grantedScopes.

Each endpoint in the REST API reference lists the codes it returns.

Errors any route can return

Status	Code (when sent)	Meaning
`401`	`API_KEY_REQUIRED`	No key in `X-API-Key` or `Authorization`.
`401`	`INVALID_API_KEY`	Unknown, revoked or expired key.
`401`	`INVALID_SESSION`	Member routes: missing, expired or not valid for this community.
`403`	`MISSING_SCOPE`	The key lacks the route's scope (`grantedScopes` lists what it has).
`403`	`SECRET_KEY_REQUIRED`	A publishable key on a secret-only route.
`403`	`WRONG_COMMUNITY`	The key belongs to another community.
`404`	`COMMUNITY_NOT_FOUND`	Unknown `communityTag`.
`429`	`RATE_LIMITED`	Over a limit; see Rate limits.
`503`		Temporarily unavailable. Retry after the `Retry-After` header.

Routes without a code

The API-key middleware and some older operator routes send no code. Branch on the HTTP status there. The JavaScript client derives one from the status in that case: BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, RATE_LIMITED, INTERNAL.

In the client

Every non-2xx answer throws a CobuntuError with status, code, message and details (the rest of the body). A request that never got an answer is status: 0, code: "NETWORK_ERROR".

import { CobuntuError } from "@cobuntu/embed";
 
try {
  await cobuntu.events.checkout("supper-club", { tierId, successUrl, cancelUrl });
} catch (e) {
  if (e instanceof CobuntuError && e.code === "TIER_FULL") {
    // show "sold out"
  } else throw e;
}

Failing safely

A 404 on an id from another community is deliberate: ownership is part of the lookup, so the API never confirms that an id names something real.
A malformed cursor is a 400, never a silent restart from the top.
Where an integration only reads to decide whether to gate a member (onboarding, for example), fail open on errors; where it writes, fail closed and say so. See Onboarding.

Security model Rate limits