Core concepts

Errors

Handle Management API status codes and validation errors.

Koneth uses HTTP status codes and JSON error bodies. Most errors contain an error string.

{
  "error": "Missing API scope: accounts:create"
}

Validation errors also include Zod issue details:

{
  "error": "Invalid request",
  "issues": [
    {
      "code": "too_small",
      "path": ["accountName"],
      "message": "Too small: expected string to have >=1 characters"
    }
  ]
}

Status codes

Status	Meaning	Retry guidance
`400`	The request body, query, path value, or idempotency key is invalid.	Fix the request before retrying.
`401`	The management key is missing, malformed, expired, revoked, or invalid.	Create and configure a replacement key, then revoke the old one if needed.
`402`	The organization has insufficient API credits.	Add credits, then retry if the operation is still needed.
`403`	The key lacks the required scope or cannot access the server.	Change the key’s access; do not retry unchanged.
`404`	The route, trading account, command, server, or wallet does not exist.	Verify identifiers before retrying.
`409`	The request conflicts with current state, such as an account-cap limit.	Resolve the conflict first.
`500`	Koneth encountered an unexpected error.	Retry a safe request with backoff and a strict limit.

Error handling example

const response = await fetch(url, options);
const body = await response.json().catch(() => ({}));

if (!response.ok) {
  const message = typeof body.error === "string"
    ? body.error
    : `Koneth request failed with HTTP ${response.status}`;

  throw new Error(message);
}