Error catalog

#The problem document

Every KYTRIX rejection is an RFC 9457 problem document served as application/problem+json. It always carries a code from the catalog below, and where a field is at fault, the dotted path to it.

{
  "type": "kytrix:validation/pan_detected",
  "title": "Payload contains a card-number (PAN) pattern",
  "status": 400,
  "code": "kytrix:validation/pan_detected",
  "detail": "data.memo: must not contain a card number",
  "instance": "/v1/movements",
  "errors": [
    {
      "path": "data.memo",
      "code": "kytrix:validation/pan_detected",
      "message": "must not contain a card number"
    }
  ],
  "correlation_id": "6f9f0f2e-6b0e-4a1d-9d2f-2f6c3f2a1b77"
}

import { ErrorCode, isKytrixApiError } from '@kytrix/sdk';

try {
  await kytrix.movements.submit(event, { idempotencyKey: row.id });
} catch (err) {
  if (!isKytrixApiError(err)) throw err;
  switch (err.code) {
    case ErrorCode.ValidationPanDetected:   // a card number reached a free-text field
      return quarantineRow(row, err.errorsAt('data.memo'));
    case ErrorCode.SequenceConflict:        // same entity version, different content
      return bumpSequenceAndRetry(row);
    case ErrorCode.IdempotencyKeyConflict:  // this key was used with a different body
      return alertOncall('idempotency key reused', err.correlationId);
    case ErrorCode.RateLimitExceeded:       // the SDK already backed off maxAttempts times
      return deferRow(row, err.rateLimit?.retryAfterSeconds ?? 60);
    default:
      throw err;
  }
}

#What is retryable

#The catalog

All 38 codes, generated from ERROR_CATALOG in packages/contracts/src/errors.ts. Codes are grouped by family; the family is the segment between kytrix: and /.

#auth/*

The request signature, the timestamp, the nonce or the credential is the problem.

#authz/*

Authenticated, but not allowed to do this.

#validation/*

The payload itself is unacceptable. Fix the mapping — a retry cannot help.

#sequence/*

A version conflict on an identity you already sent. Never a silent overwrite.

#idempotency/*

Your Idempotency-Key was used differently, or is still in flight.

#batch/*

The batch envelope broke a limit.

#reference/*

Well formed, but it points at a canonical object KYTRIX does not know. Send the referenced object first.

#rate_limit/*

You are over the per-tenant budget. Honour Retry-After.

#request/*

A transport-level limit.

#not_found/*

No such object in this tenant. Cross-tenant reads do not exist to be found.

#conflict/*

A resource-state conflict with no more specific family.

#webhook/*

The webhook endpoint URL is not one KYTRIX will deliver to.

#import/*

Something about a historical import or one of its chunks.

#tenant/*

The tenant behind the credential is unknown or suspended.

#governance/*

A governed workflow refused: approval missing, maker equals checker, an immutable object, or an illegal state transition. Mostly console surfaces.

#service/*

KYTRIX is shedding load or degraded. Retry with backoff.

#internal/*

A KYTRIX bug. Quote correlation_id to support.

#The ones you will actually meet

Most of the catalog belongs to console workflows you will never call. On the ingestion path, these are the codes worth writing a branch for on day one:

• kytrix:validation/schema — the payload does not match the contract. errors[].path names the field. This is a mapping bug.
• kytrix:validation/pan_detected — a Luhn-valid 13–19 digit run reached a free-text field. Send a token or first6/last4 at most; never the number.
• kytrix:validation/money_scale_mismatch — an amount carries more precision than its asset scale allows. KYTRIX will not round your money for you.
• kytrix:validation/unsupported_schema_version — the envelope pins a schema_version this build does not accept.
• kytrix:sequence/conflict — you resent an identity with different content and no higher sequence. For movements and control events, corrections are new events with links.correction_of.
• kytrix:idempotency/key_conflict — the same Idempotency-Key with a different body. Almost always a key-derivation bug on your side.
• kytrix:auth/timestamp_skew — your clock is more than 5 minutes off ours. Run NTP.
• kytrix:auth/nonce_replayed — you re-sent captured headers. Generate a fresh nonce per attempt, including per retry.
• kytrix:rate_limit/exceeded — over the per-tenant token bucket. Retry-After says how long to wait.