Responses & errors

Successful responses

Reading data

Responses containing information are JSON objects with the payload under a top-level Data key. Data is an object for single entities and an array for lists.

{
  "Data": {
    "Id": "14feb291-8b47-44c6-8cbb-97a3f24c33c8",
    "FirstName": "Robert",
    "LastName": "Doe",
    "Email": "[email protected]",
    "CreationDate": "2018-03-16T15:16:35+00:00",
    "PhoneNumber": "0497/12 34 56",
    "Language": "FR",
    "IsAccountant": true
  }
}

When sideloading is used, related entities are returned next to Data under an Included key.

Creating or updating data

Requests that create or update an entity return only its identifier:

{
  "Id": "14feb291-8b47-44c6-8cbb-97a3f24c33c8"
}

🚧
Updating book entries returns a new Id
Updating an invoice or an operation (invoices.*.update, book-entries.*.update) generates a new book entry. The response contains the new book entry's Id: replace the Id stored on your side.

Relationships

Related entities are represented by a type/id reference:

"ResponsibleUser": {
  "Type": "Users",
  "Id": "14feb291-8b47-44c6-8cbb-97a3f24c33c8"
}

Use the matching .info endpoint, or sideloading where available, to retrieve the related entity.

Status codes

Code	Meaning
`200`	OK.
`400`	Bad Request: the request contains invalid data or references non-existing resources.
`401`	Unauthorized: the access token is invalid, expired or missing.
`403`	Forbidden: the user or integration is not allowed to access this resource.
`404`	Not Found: the resource was not found.
`500`	Internal Server Error: something went wrong unexpectedly.

Error format

Except for authorization errors, errors return an object with three fields:

{
  "ErrorType": "not_found",
  "Details": "The requested book entry was not found.",
  "Message": "Element was not found"
}

Field	Description
`ErrorType`	Machine-readable error category. Use it in your code.
`Details`	Human-readable explanation of what went wrong.
`Message`	Short, generic message.

Handling errors

401: refresh the access token once and retry (see Token lifecycle). If it fails again, ask the user to reconnect.
400: do not retry as-is. Log Details, it usually points to the invalid field or the missing reference (unknown account, unbalanced entry, etc.).
500: retry later with exponential backoff. If the error persists, contact [email protected] with the endpoint, the timestamp and the request body.