Guides

Error handling

Branch on stable codes and retain the request ID.

One error envelope

{
  "error": {
    "code": "invalid_postcode",
    "message": "The postcode format is invalid.",
    "field": "delivery_postcode",
    "request_id": "req_example"
  }
}

field is optional. A resource belonging to another account returns 404. Provider diagnostics and database error strings are excluded.

HTTP responses

HTTP	Handling
200 / 201	Success / created
202	Reserved live manual cancellation request; not confirmation
400 / 422	Repair malformed input / schema or capability error
401 / 403	Correct credentials / permissions
404	Resource absent or unavailable in this account/mode
409	Resolve state/idempotency conflict; do not change keys blindly
413	Reduce body below 256 KiB
429	Wait Retry-After seconds with jitter
500 / 502 / 503	Temporary or unconfirmed operation; preserve booking key and investigate

Retry deliberately

Reads and quote requests can use bounded exponential backoff for transient failures. Reuse the identical booking body and Idempotency-Key after a timeout. A cached provider failure is replayed until an operator reconciles it; a fresh key could create a duplicate in a live system. Give support X-Request-ID, operation, environment and timestamp.