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.

Code	Status	Meaning
`unauthorized`	401	Missing, invalid or revoked service-account token
`forbidden`	403	Token cannot access this resource/channel
`not_found`	404	Resource does not exist in this project (also: pruned/deleted conversations)
`validation_failed`	400	Request shape invalid (`errors` extension carries field details)
`conversation_closed`	409	Customer messages rejected until reopened
`contact_blocked`	403	The contact is blocked in this project
`agent_not_capable`	400	The AI agent lacks the “Reply to customer” tool
`workflow_not_found`	404	Unknown or non-live workflow
`idempotency_in_flight`	409	Original request with this key still processing — retry after `Retry-After`
`idempotency_key_reuse`	422	Same key, different request body
`rate_limited`	429	Over budget — honor `Retry-After`
`rate_limiter_unavailable`	503	Transient infrastructure state — retry after `Retry-After`
`unsupported_version`	400	Unknown `Gleap-Version` value
`webhook_limit_reached`	409	More than 5 webhook endpoints
`payload_too_large`	413	Upload exceeds 25 MB
`upload_failed`	500	Storage/transcode failure
`internal_error`	500	Unexpected server error — safe to retry

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.

Guide

Endpoints

Errors — RFC 9457 problem details

Idempotency

Versioning & compatibility

​Errors — RFC 9457 problem details

​Idempotency

​Versioning & compatibility

Errors — RFC 9457 problem details

Idempotency

Versioning & compatibility