Errors and conventions

Response shapes

The APIs do not share one envelope. Check which you are calling.

Platform REST API wraps everything:

{ "success": true,  "data": { } }
{ "success": false, "error": "Human-readable message" }

Chain data API returns resources directly, and lists as { "items": [...], "next_page_params": {...} }.

Bridge and ICO APIs return resources directly, with errors as { "error": "message" }.

Status codes

Status	Meaning
200	Success
201	Created — a new subscription or record
400	Missing or invalid input
401	Authentication failed or absent
404	Endpoint or resource not found
429	Rate limited — see the RateLimit-* headers
500	Internal error
503	A feature is not configured on this deployment

Handling errors properly

Check the status before parsing

A common bug is parsing the body before checking whether the request succeeded. An error body has a different shape, so the parse throws and the real error — a 401, a 500 — is reported to the user as a network failure.

// wrong
const data = await response.json();
if (!response.ok) throw new Error('Request failed');

// right
if (!response.ok) {
  let detail = '';
  try { detail = (await response.json()).error ?? ''; } catch {}
  throw new Error(detail || `HTTP ${response.status}`);
}
const data = await response.json();

Amounts

Every on-chain amount is an integer in the token's base unit. Use BigInt throughout — see KNYX and denominations.

Addresses

Addresses are accepted in any case and are usually returned checksummed. Compare them case-insensitively:

a.toLowerCase() === b.toLowerCase()

Timestamps

ISO 8601 in UTC, for example 2026-09-18T18:43:31.743Z.

Pagination

The chain data API uses next_page_params; see Chain data API. Other list endpoints take limit, capped per endpoint.

Idempotency

Webhook delivery is at-least-once, so handlers must be idempotent — see Webhooks. HTTP requests to the APIs are not retried automatically; retry them yourself with backoff, and be careful with anything that spends funds.

See Troubleshooting for protocol-level errors.