Requests, responses, and errors

Database APIs return operation-specific JSON. Check the HTTP status first, then read the result shape for that operation.

Common success envelope#

Record reads and writes commonly use this envelope:

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

Property	Purpose
`status`	`success` for a completed operation
`message`	Human-readable result summary
`data`	Record, record list, or operation-specific result
`total`	Count associated with a collection result

total is omitted when an operation does not return a collection count.

Record operations#

Create one or many#

POST /data/ accepts one object or an array and returns HTTP 201. Created records are always returned as an array:

{
  "status": "success",
  "message": "Successfully created 1 record(s)",
  "data": [
    {
      "id": "2eeb6c5f-c8ce-4e3b-a6b8-0472502ad743",
      "title": "Prepare launch notes",
      "done": false
    }
  ],
  "total": 1
}

For a single create, the created record is data[0].

List#

A list returns HTTP 200, records in data, and the full matching count in total:

{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": [
    {
      "id": "2eeb6c5f-c8ce-4e3b-a6b8-0472502ad743",
      "title": "Prepare launch notes",
      "done": false
    }
  ],
  "total": 1
}

total is calculated before the requested page is sliced. Use page and page_size to choose the returned window.

No matches is also a successful result:

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

Read one#

A direct read returns one object in data:

{
  "status": "success",
  "message": "Record retrieved successfully",
  "data": {
    "id": "2eeb6c5f-c8ce-4e3b-a6b8-0472502ad743",
    "title": "Prepare launch notes",
    "done": false
  }
}

Update one#

A single update returns the updated object:

{
  "status": "success",
  "message": "Record updated successfully",
  "data": {
    "id": "2eeb6c5f-c8ce-4e3b-a6b8-0472502ad743",
    "title": "Publish launch notes",
    "done": true
  }
}

Bulk update#

Bulk updates return records and a count inside data:

{
  "status": "success",
  "message": "Successfully updated 2 record(s)",
  "data": {
    "records": [
      {
        "id": "2eeb6c5f-c8ce-4e3b-a6b8-0472502ad743",
        "done": true
      },
      {
        "id": "f52b46dc-d7f8-44ab-b8a4-25e236518e04",
        "done": true
      }
    ],
    "count": 2
  }
}

Delete#

Deleting one record returns HTTP 204 with no response body.

Deleting a collection by explicit IDs returns a plain result object:

{
  "deleted_count": 2,
  "message": "Successfully deleted 2 record(s)"
}

Collection delete does not use the common status and data envelope.

SDK result mapping#

The REST examples above show the wire response. Client libraries expose it as follows:

Interface call	Result
JavaScript builder list/read `execute()`	TaruviBase wire response; collection reads also include `total`
Python builder list/read `execute()`	Normalized object containing `data` and `total`; direct-ID builder reads use the record object in `data` and `total: 0`
JavaScript or Python builder create/update `execute()`	TaruviBase success envelope for that mutation
JavaScript builder single-delete `execute()`	Empty response payload from HTTP `204`
Python builder single-delete `execute()`	Empty object `{}` from HTTP `204`
JavaScript or Python builder ID-bulk-delete `execute()`	Plain object containing `deleted_count` and `message`
Python direct `create()`	Created-record list
Python direct `get()` or single-record `update()`	Record object
Python direct single-record `delete()`	`None` after HTTP `204`
Refine `getList`	`{data, total}` in Refine's data-provider contract
Refine `getOne` / `useOne`	Provider returns `{data}`; Refine 5 exposes the record directly as hook `result`
Refine `getMany` / `useMany`	Provider returns `{data}`; Refine 5 exposes that response as hook `result`, with records in `result.data`

Do not apply a REST data[0] access pattern to Python's direct methods; those methods already unwrap the HTTP envelope.

Structured errors#

TaruviBase errors include a stable code and a human-readable message:

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

An error can also include:

Property	Purpose
`detail`	Additional context about the failure
`errors`	Field-level or request-level validation messages
`data`	Structured context for a conflict or failed operation

Use code for application branching. Use message for a concise explanation and errors for field-level feedback.

HTTP status and code#

HTTP status	Code	Check
`400`	`BAD_REQUEST` or `VALIDATION_ERROR`	Body shape, field types, constraints, and query values
`401`	`UNAUTHORIZED`	Credential type, value, and expiry
`403`	`FORBIDDEN`	Caller role, app scope, table action, and row policy
`404`	`NOT_FOUND`	Site URL, app slug, table name, and record ID
`409`	`CONFLICT`	Primary keys, unique values, and foreign-key dependencies
`500`	`INTERNAL_ERROR`	Request identifier and service status
`504`	`GATEWAY_TIMEOUT`	Page size and query complexity
`402`	`account_suspended`	The organization's account isn't active; retrying won't help
`429`	`product_suspended`	The plan's Database usage for this period is used up; `module` names the product
`503`	`gate_unavailable`	Billing status couldn't be read; retry shortly

Billing refusals return detail, code, and module without status or message. The JavaScript and Python SDKs raise BillingError with code, module, and retryable, which is true only for gate_unavailable.

A collection read with no matches returns 200 and an empty data array. A direct read for an unknown ID returns 404 when the caller has read access.

Response handling checklist#

Check the HTTP status.
Parse JSON only when the response has a body.
Read the operation-specific success shape.
On failure, branch on code and retain detail or errors.
Record the time, operation, and status, without credentials or sensitive record values.
Before retrying a write after an interrupted request, read the target state.

Continue with: