Errors and versioning
Structured failure responses and the recovery action each status requires.
| Status | Meaning | Recovery |
|---|---|---|
| 400 | A parameter, identifier or cursor is invalid. | Correct the request. |
| 401 | The bearer token is missing or invalid. | Replace the token without changing the URL. |
| 404 | The resource or published record does not exist. | Continue ordered sync when resolving a change URL. |
| 409 | The snapshot, checkpoint or generation must restart. | Take a new full snapshot. |
| 429 | The request limit has been reached. | Back off before retrying. |
| 503 | Partner Demand is unavailable or not configured. | Retain the last coherent local snapshot and retry later. |
Breaking contract changes use a new URL version. Additive fields may appear within v1 after documentation. A deprecated version receives at least 90 days notice through the partner change process.
Fail closed and retain coherence
An error response uses a structured envelope. It does not return raw upstream errors, database details or authorization hints.
For temporary failures, keep the last coherent local snapshot and mark its checked time. Do not merge a partial response into that snapshot. A 409 is different from a retryable transport failure: it invalidates the incremental path and requires a fresh snapshot.
Compatibility
Clients should:
- require the supported
api_version; - ignore additive response fields they do not use;
- load bounded enum labels from taxonomy;
- reject a missing or invalid public generation; and
- treat a new URL version as a separate contract and local sync namespace.
The committed OpenAPI contract is the machine-readable source for operations, parameters and response shapes.