Skip to main content
A send either resolves to a SendResult or throws an error that tells you what happened. This page covers the retry rules, the idempotency guarantees, and the full error surface, including the one distinction that matters most when catching: transport failures and configuration failures are different error types.

​
Idempotency

If you omit idempotencyKey, the client mints one UUID per send and reuses it across every internal retry, so a flaky connection cannot produce a duplicate. That minted key protects only the retries inside that one call. To make repeats safe across process restarts and queue redeliveries, pass your own key naming the business fact:
The server remembers caller-supplied keys for 24 hours; a repeat with the same payload returns the original message, and a repeat with a different payload is rejected. The details are on the HTTP API page.

​
What retries automatically

Up to three retries follow the initial attempt (four attempts total by default). Backoff starts at retryBaseDelayMs, uses bounded jitter, and never exceeds retryMaxDelayMs or the remaining operation deadline. Valid delta-seconds and HTTP-date Retry-After values can extend that delay. Every attempt is bounded by both attemptTimeoutMs and the remaining operationTimeoutMs budget.

​
Handling errors

HTTP rejections throw RepostPublishError, which carries the HTTP status, parsed bounded JSON body, and structured delivery metadata. Network, timeout, cancellation, deadline, and overload failures throw RepostTransportError:
Stable error messages come from the exported error catalog: The payload cap is checked before the first attempt, so an oversized event never reaches the network.
Configuration, validation, serialization, transport, publish, and descriptor-version failures have distinct exported error classes. They all extend RepostError and expose the same structured metadata fields.
Validation errors are coded and name the exact path:
  • REQUIRED at $.id when a required field is absent
  • [NULL_NOT_ALLOWED] when null is passed for a non-nullable field
  • TYPE_MISMATCH, OUT_OF_RANGE, NON_FINITE, INVALID_DATETIME, INVALID_ENUM, INVALID_JSON, and INVALID_UNICODE for malformed values
These are bugs to fix, not requests to retry.

​
What goes on the wire

Payloads serialize deterministically: fields in schema declaration order under their @map wire names, absent optional fields omitted (or their @default injected), explicit null only where the schema allows it, and timestamps in the ISO-8601 millisecond UTC form. Input properties that aren’t in the schema are dropped. A value you provide is never overridden by a default. The envelope has exactly the keys type, timestamp, data, in that order.

​
Continue

Testing

Exercise these paths without a network.

Configuration

The transport options behind the retry behavior.

Delivery & retries

What happens to the message once Repost accepts it.