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);
}

Note

An HTTP 202 response means the request was accepted, not completed. Track the returned command until it reaches a terminal status.

Errors that arrive on the command, not the response

Account operations are accepted (202) and executed on the trading server, so a rule violation is reported when you poll the command rather than on the request that queued it. status is failed and errorCode names the reason; errorMessage is written for an operator, not for branching on.

errorCode	Meaning
LEVERAGE_ABOVE_MAXIMUM	The leverage exceeds the maximum the organisation set on the server.
UNLIMITED_LEVERAGE_UNAVAILABLE	unlimitedLeverage was requested but the server still has a leverage ceiling. Remove it in Console under the server’s Configure, then queue the account again.
INVALID_LEVERAGE	The leverage is not a positive whole number.
OPEN_EXPOSURE_REQUIRES_VALUATION	The account has open positions, and changing its leverage would change their margin. Close them first.
INVALID_COMMAND	The command payload failed validation.

Do not retry a failed command unchanged: it is deterministic, and the same request produces the same rejection.