This policy defines which changes to the Lobyco API are breaking, which changes an API client must tolerate without notice, and how much notice Lobyco gives before a breaking change takes effect.
Scope
This policy covers the endpoints, fields and behaviour documented in the API Reference. Undocumented behaviour is not part of the API contract and can change without notice.
What is a breaking change?
A breaking change is a change to the documented API after which an API client no longer works correctly unless it is updated.
The following are breaking changes:
- Removing or renaming an endpoint, parameter, request field or response field.
- Changing the data type or format of a field.
- Changing the meaning of an existing field or value.
- Adding a value to a response field whose allowed values are not documented as extensible.
- Removing an allowed value from a request field.
- Adding a required parameter or request field, or making an optional one required.
- Tightening validation on existing parameters or fields.
- Changing the permission scopes or access rights an endpoint requires.
- Changing the documented behaviour of an endpoint.
- Lowering rate limits or making the throttling policy stricter.
What is a non-breaking change?
A non-breaking change is one that an API client built to the requirements below keeps working through without an update. Lobyco makes non-breaking changes at any time, without notice and without releasing a new API version.
Every API client must tolerate the following changes:
- New fields in response objects, and in payloads Lobyco sends to the API client.
- New HTTP response headers.
- A different order of fields within a JSON object.
- A different order of items in an array, unless the API Reference documents a sort order.
- New values in a response field whose allowed values are documented as extensible.
- Changes to the length or format of identifiers and other opaque strings, unless the API Reference documents a format.
- Changes to human-readable text, such as error messages.
The following non-breaking changes need no action:
- New endpoints.
- New optional parameters and request fields, and validation rules that apply only to them.
- New allowed values in request fields.
- Deprecation of an endpoint or field. A deprecated endpoint or field keeps working until its announced removal date, and its removal is a breaking change.
Requirements for API clients
Every API client must be a tolerant reader and meet these requirements:
- Ignore unknown fields. The client must not fail on fields it does not recognise, or validate responses against a schema that forbids additional fields.
- Read fields by name. The client must not rely on the position of a field.
- Handle unknown values in extensible fields. When such a field returns a value the client does not recognise, the client must fall back to safe default behaviour instead of failing.
- Treat identifiers as opaque strings. The client must not parse identifiers or store them in fixed-length fields.
- Ignore human-readable text. The client must base its error handling on the HTTP status code, not on the wording of a message.
- Rely only on documented behaviour. The client must not depend on behaviour the API Reference does not document.
If an API client fails because of a non-breaking change, the cause is in the integration. The failure is not a breaking change, and the notice period does not apply to it.
Notification policy
When Lobyco plans a breaking change:
- Lobyco keeps both versions of the affected API available for at least 6 months, where feasible.
- Lobyco announces what changes, the date it takes effect and the action required, through:
Exceptions
Lobyco may make a breaking change with shorter notice, or none, when the change is needed to:
- Fix a security vulnerability.
- Comply with a legal or regulatory requirement.
- Fix a critical bug.
In these cases Lobyco notifies affected organisations as soon as possible, through the channels listed above. Last modified on September 29, 2026
