Conventions

Error envelope#

Every error response — whatever the status code — uses the same shape:

{
  "error": {
    "code": "STUDENT_NOT_FOUND",
    "message": "Student not found.",
    "details": {
      "studentId": "0190a1b2-..."
    },
    "requestId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b"
  }
}

message is always English and meant for logs, not end users — translate by code in your own UI. details is present only when it adds something a client can act on (which field failed validation, which id was looked up). requestId matches the value the API also logs server-side — include it when reporting an issue.

Error codes#

Every code the API can return, generated directly from packages/shared/src/errors.ts — the single source every error factory in the codebase constructs from, so this table can never drift from what the API actually sends.

400 vs 422#

Validation is always 422. Anything the API reads but will not accept — a body, query string, path parameter or header that fails its schema, or a domain rule rejecting a well-formed value — comes back as 422 VALIDATION_ERROR, and a schema failure carries the failing fields in details.issues:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input: expected string, received undefined",
    "details": {
      "issues": [
        {
          "path": [
            "branchId"
          ],
          "message": "Invalid input"
        }
      ]
    },
    "requestId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b"
  }
}

400 MALFORMED_REQUEST means only that the request could not be read at all — unparseable JSON, an unusable Content-Type, an oversized payload. In short: a 400 is a bug in how you serialise the request, a 422 is a bug in what you put in it. A handful of endpoints also use 400 for one specific named rejection (INVITATION_INVALID, LICENSE_INVALID, OAUTH_INVALID_REDIRECT_URI) — which is why you branch on error.code, never on the status.

Cursor pagination#

Every list endpoint is cursor-paginated — never offset/page-number, so results stay correct even while rows are being inserted concurrently. Pass limit (max 100, default varies by endpoint) and, for every page after the first, the cursor from the previous page's response:

{
  "data": [
    "…"
  ],
  "nextCursor": "eyJpZCI6IjAxOTAwMDAwLTAwMDAtNzAwMC04MDAwLTAwMDAwMDAwMDAwMSJ9"
}

nextCursor is string | null — null means you've reached the last page. Treat the cursor as opaque: it's a base64url-encoded pointer, not a row offset, and its internal shape may change.

Money#

Every monetary value is a nested object — { amountMinor, currency } — an integer in the currency's minor unit (cents, agorot, fils) paired with its own currency field on that same object, e.g. an invoice's total.amountMinor + total.currency, a payment's amountMinor + currency. It is never a bare number with the currency living somewhere else on the parent object. Never a float. { amountMinor: 1250, currency: "USD" } is $12.50.

Timestamps#

Every timestamp is ISO-8601 in UTC (2026-03-02T09:00:00.000Z). Dates with no time component (a due date, a date of birth) are plain YYYY-MM-DD. Convert to the tenant's timezone (default Asia/Jerusalem) for display — the API never does this for you.

Multi-tenancy#

You never pass a tenant id yourself. A first-party JWT carries the tenant chosen at select-tenant time; an API key is permanently bound to the tenant it was created in. Every query the API runs is scoped to that tenant at both the application layer and the database's own row-level security — there is no way to address another tenant's data by guessing an id.