The error envelope

Errors are returned as JSON with a stable shape. violations and timestamp are omitted when empty:

  {
  "error": "VALIDATION_ERROR",
  "message": "Transaction block must balance",
  "violations": ["entries: sum of debits (125000) != sum of credits (100000)"],
  "timestamp": "2026-07-01T09:14:03.512Z"
}

Two write-path errors use specialized shapes:

Batch size exceeded (413):

  {
  "error": "BATCH_SIZE_EXCEEDED",
  "message": "Batch size 1500 exceeds maximum allowed size of 1000",
  "maxBatchSize": 1000,
  "requestedSize": 1500
}

Idempotency / conflict responses on event submission (409) include the conflicting entries per domain:

  {
  "error": "Conflicting derivations for account",
  "accountReference": "2700-vat-out",
  "conflictingEntries": {
    "domain-a": [
      { "accountReference": "2700-vat-out", "amountMinorUnits": 25000, "entryType": "CREDIT" }
    ]
  }
}

HTTP status codes

StatusMeaning in Ledger17
200 OKRead succeeded
201 CreatedTransaction or correction recorded; Location header points to the resource
202 AcceptedBusiness event accepted for asynchronous processing
204 No ContentDeletion succeeded (dead-letter queue)
400 Bad RequestValidation failure — unbalanced block, missing field, bad enum value, missing idempotency key
403 ForbiddenToken lacks the required tenant permission
404 Not FoundUnknown transaction or resource
409 ConflictIdempotency-key replay, duplicate documentReference, or conflicting rule-set derivations
413 Payload Too LargeTransaction batch exceeds the size limit
422 Unprocessable EntityBatch import failed validation (per-item errors in the body)
500 Internal Server ErrorUnexpected failure

Error-code catalog

Values of the error field you can program against:

CodeWhere
VALIDATION_ERRORAny request that fails bean validation
BAD_REQUESTMalformed JSON
INVALID_ARGUMENTInvalid parameter values
UNBALANCED_TRANSACTIONΣ debits ≠ Σ credits
IDEMPOTENCY_CONFLICTX-Idempotency-Key already used; violations contains existingTransactionId=<uuid>
DUPLICATE_DOCUMENT_REFERENCEBatch import: documentReference already exists for tenant
CONFLICT_DETECTEDRule sets derived contradictory entries
ONTOLOGY_VALIDATION_ERRORBusiness event violates the rule set’s ontology
FORBIDDEN, TENANT_ACCESS_DENIEDPermission failures
TRANSACTION_NOT_FOUND, NOT_FOUNDUnknown resources
BATCH_SIZE_EXCEEDEDTransaction batch too large
EVENT_PROCESSING_ERROR, SERIALIZATION_ERROR, INTERNAL_ERRORServer-side failures