Errors

Errors follow RFC 9457 and use application/problem+json:

{
  "type": "https://docs.api.ambula.nl/errors/validation_failed",
  "title": "Validation failed",
  "status": 400,
  "code": "validation_failed",
  "detail": "The request body is invalid.",
  "request_id": "req_4f1c9a",
  "errors": [{ "path": "date", "message": "Invalid date" }]
}

Branch on code, which stays stable. title and detail are for people and can be reworded.

Statuses

Status	Meaning
400	Malformed request or invalid parameters. errors[] lists each invalid field
401	Missing, invalid, expired or revoked API key
403	The key lacks a scope, or your company doesn’t have the module
404	Not found. Also the answer for a record of another company
409	Conflict, such as an idempotent request that’s still running
412	If-Match didn’t match: the record changed since you read it
422	Understood but not allowed, such as a step only a driver can take
429	Rate limit or quota reached. Wait for Retry-After seconds
5xx	Something failed on Ambula’s side. Retry with the same Idempotency-Key

Retrying

Retry 429 and 5xx with exponential backoff, and keep the Idempotency-Key of the original POST so a retry can’t create a second record. Don’t retry other 4xx unchanged: they won’t succeed until the request changes.