Error reference

Kraty errors are sealed: every non-2xx response carries a code from a known set, plus a human-readable message and an optional structured details. Codes are stable: a new code is a breaking change, never silently introduced.

Response envelope

{
  "error": {
    "code": "insufficient_entry_cost",
    "message": "not enough cash to enter, need 50",
    "details": { "resource": "cash", "needed": 50, "have": 30 }
  }
}

Code reference

Grouped by HTTP status. Every code has a typed is… getter on the SDK's error class. Match on the getter, not on a string comparison. The "SDK helper" column lists the canonical getter name; each SDK adapts to its language convention:

For codes the SDK has not been bumped to know about yet, use the generic escape hatch:

• TS / Dart: err.is('code_string') (or err.isCode(...) in Dart)
• C#: err.Is("code_string")
• Python: err.is_code("code_string")

400 Bad Request

401 Unauthenticated

402 Payment Required

403 Forbidden

422 Unprocessable Entity

404 Not Found

409 Conflict

429 Too Many Requests

500 Internal Error

202 (special) Lobby forming

Portal / member-management codes

These fire on the portal session surface (/admin/v1 and the member-OAuth login flow). They are never returned to game clients through /sdk/v1, so SDK consumers can ignore them; they exist for the portal UI and for any internal tooling you build against the admin API.

Handling patterns

Typed handling with helper getters

try {
  await kraty.events.start('bounty_hunt');
} on KratyApiError catch (err) {
  if (err.isLobbyForming) {
    final lobbyId = (err.details as Map)['lobbyId'] as String;
    await pollLobbyUntilActive(kraty.lobbies, lobbyId);
  } else if (err.isInsufficientEntryCost) {
    showInsufficientResourceDialog(err.message);
  } else if (err.isPlayerSecretInvalid) {
    await reregister();
  } else if (err.isEntryRequirementFailed) {
    showLockedEventDialog(err.message);
  } else {
    rethrow;
  }
}

Switch on code for the rest

try {
  await kraty.events.progress(...);
} on KratyApiError catch (err) {
  switch (err.code) {
    case KratyErrorCode.noActiveWindow:
      showToast('Event has not started yet.');
      break;
    case KratyErrorCode.maxAttemptsReached:
      showToast('Out of tries. Come back next round.');
      break;
    case KratyErrorCode.attemptFinished:
      // server-side completion races client; just refresh state
      await kraty.grants.collectAll();
      break;
    default:
      rethrow;
  }
}

Network failures

KratyNetworkError covers everything that did not produce an HTTP response (DNS, socket reset, timeout). The SDK auto-retries network errors with backoff before surfacing this.

try {
  await kraty.events.listForPlayer();
} on KratyNetworkError catch (err) {
  // Backend unreachable. Show offline UI, queue actions for later.
  print('Network: ${err.message}');
  print('Original: ${err.originalCause}');
}

A KratyNetworkError is not a Kraty outage. A degraded backend answers with 5xx or times out; a name-resolution or no-route failure means the request never left the device. On mobile the triggers are almost always device-side: Android waking from doze with a stale network handle, captive-portal Wi-Fi, airplane mode, or a carrier resolver that is briefly unreachable after a Wi-Fi-to-cellular handover.

Handle it as an offline state, not an exception path: show cached data, queue the write, retry on the next interaction. Every write carries an auto-generated idempotency key preserved across retries, so re-issuing a failed mutation later can never double-apply it.

The Unity SDK additionally backs off connectivity failures on a slower ladder than server errors, since a resolver needs seconds rather than milliseconds to recover -- see Unity → Offline is not a crash.

Idempotency replays

Replaying a write with the same idempotencyKey and the same body returns the original response: no error, no double-effect. Replay with a different body returns 409 idempotency_conflict.

The SDK auto-generates an idempotency key per POST / PUT / PATCH and preserves it across retries, so a network failure between request-send and response-receive is replay-safe by default.

Rate limiting

429 rate_limited carries a Retry-After header. The SDK honours it automatically, so you only see the 429 surface as a thrown error if all retry attempts (default 4) exhausted the budget.

If you are a studio backend hitting /server/v1 hard for batch fulfilment, prefer fewer larger requests over many small ones. Per-key rate limits today: client_sdk keys get a read/write split (~600 reads/min, ~120 writes/min); server_integration keys get ~1000 req/min. See the full table in REST API → Rate limits.

Constants

All codes are exported as KratyErrorCode constants in the Flutter SDK so you can compare without typos:

import 'package:kraty/kraty.dart';

if (err.code == KratyErrorCode.insufficientEntryCost) { ... }

The full list mirrors the table above. Adding a new code is a breaking SDK change and bumps the minor version, so pin a specific SDK version in your pubspec.yaml / package.json to stay in control.