Errors, idempotency & versioning

Errors — RFC 9457 problem details

Every error is application/problem+json with a stable machine-readable code:

{ "type": "https://docs.gleap.io/s2s/problems/conversation_closed",
  "title": "Conversation Closed", "status": 409, "code": "conversation_closed",
  "detail": "This conversation is closed. Reopen it to send messages.",
  "request_id": "req_66c0ffee0000000000000001" }

Branch on code, never on detail (human wording can change). Every response — success or error — carries a Gleap-Request-Id header; include it when contacting support about a request.

Idempotency

Send an Idempotency-Key header (≤255 chars, e.g. a UUID) on any POST you might retry:

• A successful response is stored and replayed for 24 hours — replays carry Gleap-Idempotency-Replayed: true and are byte-equivalent (file URLs re-signed fresh).

• Error responses are never stored — retry them normally with the same key.

• The same key with a different body returns 422 idempotency_key_reuse.

• Semantics are at-least-once: a retry racing a crashed or >60-second-running original may re-execute. Design consumers to tolerate a rare duplicate (e.g. reconcile by conversation number/content), as you would with Stripe-style idempotency.

Versioning & compatibility

• Pin with Gleap-Version: 2026-08-01; responses echo the resolved version.

• Within a version, changes are additive only — ignore unknown fields and unknown event types.

• Breaking changes ship as a new dated version; the previous version remains supported for at least 12 months with written notice.