API request lifecycle

Every request to TaruviBase passes through the same checks, in this order:

Route. The site address selects your site, and the path selects the app and resource.
Authenticate. TaruviBase reads the session token, API key, or JWT and identifies the caller.
Validate. The path, query parameters, and body are checked against the operation.
Authorize. The caller's roles and the app's access policies decide whether the action is allowed.
Respond. The result returns in a standard JSON envelope.

Response envelope#

Successful responses include status, message, and data. List responses also include total:

{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": [],
  "total": 0
}

Errors include a code and message, and may add detail or field-level errors:

{
  "status": "error",
  "message": "Validation failed",
  "code": "VALIDATION_ERROR",
  "errors": {"title": ["This field is required."]}
}

Billing refusals are the exception: they carry detail, code, and module, and no message:

{"detail": "…", "code": "product_suspended", "module": "database"}

They come with 402 (account_suspended), 429 (product_suspended), or 503 (gate_unavailable), and both SDKs raise BillingError for them.

Failures at different steps can look alike, so check them in the same order the request travels:

Address and path — TARUVI_SITE_URL, the app slug, the path, and the method.
Credential — a 401 means it is missing, invalid, expired, or from a different site.
Request body and parameters — a 400 with VALIDATION_ERROR lists the fields to fix.
Permissions — a 403 means the caller is known but not allowed; check roles and access policies.
Billing — a 402, 429, or 503 with one of the billing codes means the organization's billing blocked the request. Only gate_unavailable is worth retrying.
The operation itself — for other 5xx responses, note the time and the operation, retry reads, and read the current state before retrying a write.