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 hasn't 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're 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('player_42', '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 hasn\'t 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(externalId);
      break;
    default:
      rethrow;
  }
}

Network failures

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

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

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 — you only see the 429 surface as a thrown error if all retry attempts (default 3) exhausted the budget.

If you're a studio backend hitting /server/v1 hard for batch fulfilment, prefer fewer larger requests over many small ones. Per- key rate limits sit at ~600 req/min for client_sdk and ~1000/min for server_integration today.

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 — track the changelog.