Conventions #

The rules every endpoint of the books API follows. They are also published by the API itself at GET /meta, so a client can read them at run time instead of hard-coding them.

Keys and spelling #

Where	Convention	Example
Request bodies	snake_case	`transaction_date`, `account_type`
Query parameters	hyphenated	`start-date`, `account-type`
Page size	camelCase	`perPage`
Report payloads	camelCase	`balanceSheet`, `endDate`

Because the conventions differ, the API also accepts the other spellings of any key it declares: start_date and startDate both mean start-date, and per_page means perPage. Sending two spellings of the same key with different values is a 422.

Unknown keys are rejected #

A key the endpoint does not declare is an error, not something silently ignored. Previously a misspelling such as witholding_tax returned 200, but the resource was not created as you intended.

Bodies. A create or update with an undeclared key returns 422, naming the key and the accepted fields. Line items inside a transaction are checked the same way, and their errors are reported as line_items.{index}.{field}.
Query strings. A read with an undeclared query parameter returns 422. page is always accepted.
Tolerated. entity_id is accepted everywhere. The server sets it from your token regardless.

{
  "status": "error",
  "detail_code": 422,
  "help": "https://microbooks.io/docs/how-to-guides/taxes/#errors",
  "errors": {
    "witholding_tax": ["The witholding_tax field is not recognised. Accepted fields: account_id, code, entity_id, name, rate, withholding_tax."]
  }
}

Responses #

Request	Status	Body
Create	`201 Created`, with a `Location` header	`{"status": "success", "message": "...", "resource": {...}}`
Read one, update, delete, actions	`200 OK`	`{"status": "success", "resource": {...}}` or a named key such as `statement`
List	`200 OK`	`{"status": "success", "data": [...], "meta": {...}}`; see Pagination and Filtering
Reports	`200 OK`	`{"status": "success", "income_statement": {...}}` (or HTML, PDF or text with `format`)

Errors #

Every error has the same envelope:

{
  "status": "error",
  "detail_code": 422,
  "help": "https://microbooks.io/docs/how-to-guides/accounts/#errors",
  "errors": { "name": ["The name field is required."] }
}

detail_code classifies the error. Request-level problems carry a code equal to their HTTP status, listed below. Bookkeeping errors carry a per-resource code from 100 up, listed in the Errors section of each How To Guide. The two ranges never overlap.
help is an absolute link to the guide that explains the error.
errors names the field at fault. For bookkeeping errors it holds the message, the detail code and the help link per field.

Detail Code	HTTP Status	Name	Definition
401	401	Unauthenticated	No valid bearer token was presented. The `WWW-Authenticate` header points to the authorization server metadata
402	402	Payment Required	The subscription has expired, or the plan’s monthly transaction cap has been reached. Reads stay open
403	403	Forbidden	The token lacks the scope the request needs (`books:read` for reads, `books:write` for writes), or only the owner of the books may make this change
404	404	Resource Not Found	The resource does not exist, belongs to another entity, or the route does not exist
405	405	Method Not Allowed	The route exists but not for this HTTP method
422	422	Validation	A field is missing or malformed, a key is not recognised, two spellings of a key conflict, or a header such as `Idempotency-Key` or `rollback` is misused
118	422	Line Item Validation	A line item inside a transaction failed validation. Errors are keyed `line_items.{index}.{field}`
429	429	Too Many Requests	The rate limit or the plan’s monthly API call cap was reached. Retry after the `Retry-After` interval
500	500	Server Error	An unexpected error. Nothing was saved, so the request can be retried

Bookkeeping errors are returned with HTTP 400.

No partial writes
A request either succeeds completely or saves nothing. Any error response, 4xx or 5xx, rolls back everything the request wrote.