Skip to main content

​
Errors

Everything throws — there are no error-shaped return values: GoliathOperationError is the one to handle in normal application flow — it means the gateway accepted and ran your call, but the operation itself reported errors.

​
Retries (built in)

  • Both 429s are pre-execution rejections — retried for any operation, honoring Retry-After exactly.
  • Network errors, timeouts, and 5xxs are retried only when a re-send cannot double-fire a side effect: queries, or mutations sent with an idempotencyKey.
  • A mutation without an idempotency key is never re-sent.
  • Backoff is exponential with full jitter: 500ms base, 8s cap.

​
Idempotency

Every mutation accepts options.idempotencyKey:
Always pass one on writes — the client never re-sends an unkeyed mutation, so without a key a timed-out request is simply lost to you, and retrying it by hand can double-fire. Passing idempotencyKey to a read is a compile error, matching the 400 the gateway returns at runtime. The key is any string of 1-255 characters (a UUID is the obvious choice). The gateway reserves it before executing and stores the response when the request completes; keys expire after 24 hours.
Detecting replaysWhen a retried write was already executed, the gateway replays the stored response instead of re-running it. Replays surface through the onMeta callback (meta.replayed === true) — including replays whose stored body carries errors.
When a key is handed backA failure that provably happened before the write took effect — bad variables, an invalid phone number, a Do-Not-Contact block — releases the key, so you can correct the request and retry with the same one. A key whose original request is still in flight returns GoliathIdempotencyConflictError (409): retry shortly with the same key to pick up its stored result.