Skip to main content

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": []
}
PropertyPurpose
statussuccess for a completed operation
messageHuman-readable result summary
dataRecord, record list, or operation-specific result
totalCount 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 callResult
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 / useOneProvider returns {data}; Refine 5 exposes the record directly as hook result
Refine getMany / useManyProvider 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:

PropertyPurpose
detailAdditional context about the failure
errorsField-level or request-level validation messages
dataStructured 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 statusCodeCheck
400BAD_REQUEST or VALIDATION_ERRORBody shape, field types, constraints, and query values
401UNAUTHORIZEDCredential type, value, and expiry
403FORBIDDENCaller role, app scope, table action, and row policy
404NOT_FOUNDSite URL, app slug, table name, and record ID
409CONFLICTPrimary keys, unique values, and foreign-key dependencies
500INTERNAL_ERRORRequest identifier and service status
504GATEWAY_TIMEOUTPage size and query complexity

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​

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

Continue with: