Errors and retries
The TypeScript SDK's one error type, RequestError, and its codes; which calls it sends again, and how idempotency keys make a send safe to retry.
Every failed call rejects with a RequestError, which the SDK exports with
isRequestError. It takes one from any copy of the package, by its brand,
and no other library's error of that name:
| Field | What it is |
|---|---|
kind | http (the API answered a failure), network, timeout, parse (an answer that could not be read), or abort (the call's signal). |
status | The HTTP status; 0 when nothing answered. |
code | The API's error, a snake_case code such as domain_not_verified; null when the answer names none. |
body | The answer as it came, typed unknown: its JSON when it parsed (from the API, an ErrorOrValidation: a validation_failed one carries its issues), else its text, else null. Narrow it before reading it. |
retryable | true when nobody answered: the network failed, the call timed out, or a gateway answered 502, 503 or 504. It says the API may answer in a moment, not that sending again is safe: a write without an idempotency key may have landed, so read the state back first. A 429 is not retryable, yet always temporary: wait its Retry-After, then send again. |
response | The Response, when one came: an http or a parse failure. |
attempts | How many times the call was sent. |
import { isRequestError } from '@openemail/sdk'
try {
await openemail.domains.create({ domain: 'example.com' })
} catch (error) {
if (!isRequestError(error) || error.code !== 'domain_claimed_elsewhere') throw error // another account holds it
}A domain's codes show why: domains.create answers 400 domain_not_verified
until the domain's ownership record is published (the answer names it), 409 domain_claimed_elsewhere when another account holds the domain, and 409 domain_unavailable for every other conflict, worded alike on purpose so that no
one can learn which domains exist.
The SDK types no refusal's body, but reads the one a first domains.create
needs: ownershipRecordOf(error) gives the record to publish as a DnsRecord,
its shape checked first, and null for any other error.
import { ownershipRecordOf } from '@openemail/sdk'
try {
await openemail.domains.create({ domain: 'example.com' })
} catch (error) {
const record = ownershipRecordOf(error) // null for any other error
if (!record) throw error
console.log(record.type, record.name, record.value) // publish it, then create again
}Decide on the code, never on the status alone: one status covers several
conditions. Each method's page lists the refusals its operation documents, by
status, with their codes, as domains.create
does, and Error codes lists every code
with its statuses and the methods that can answer it. The API's conventions are in the
API reference's overview.
A bad argument (an option the operation does not take, a missing path
parameter) rejects with a TypeError instead, and nothing is sent.
Retries and idempotent sends
-
A read (
GET) is retried by the client's policy: on what nobody answered (the network, a timeout,502to504), and on408and429, with jittered backoff, andRetry-Afterhonoured up tomaxRetryAfter(3 s by default: a longer wait is the caller's). -
A send that takes an idempotency key (
x-delivery-id:messages.send,.sendDraft,.append,.compose,threads.reply,templates.send, the MTA doors) gets a fresh one when the call gives none (deliveryId: 'sdk_<uuid>', the same for each of the call's retries), and is retried like a read: the API converges on one send. Pass your own key to make your own retries safe too. After a send that failed,deliveryIdOf(error)answers the key it went out with (yours, or the one the SDK made), so a later send with it converges too:import { deliveryIdOf } from '@openemail/sdk' try { await openemail.messages.send(mailboxId, email) } catch (error) { const deliveryId = deliveryIdOf(error) // null for any other error if (deliveryId) await openemail.messages.send(mailboxId, email, { deliveryId }) } -
identities.updatetakes anidempotencyKeyonly for a control change (suspended,receiveHold); the API refuses one on any other (400 idempotency_key_unsupported), so the client never fills it: pass your own with a control change, and it is then yours to retry. -
identities.createthat names a webhook (messageWebhook,eventWebhook) requires anIdempotency-Keyheader, 1 to 128 characters, which the API's document does not list as a parameter: send it in the call'sheaders({ headers: { 'Idempotency-Key': key } }). A retry with the same key and body answers the same identity; it is yours to make, as the client sends such a create once. -
Any other write is never sent twice blind: a
POSTwhose answer was lost may have landed. It is sent once more only when the API refused it before doing anything, a429(a rate limit, always temporary), after theRetry-Afterit asks for, when that is withinmaxRetryAfter. A long hold (a paused sender's429 sending_paused) is the caller's to wait out. A503 temporary_failureis not sent again: the API says a write that got it may have been applied, so read the state back, or send it again with an idempotency key where the operation takes one. -
A call's own
retrywins over all of this:retry: false, or a policy, which vouches that sending it twice is harmless. A client made withretry: falseretries nothing a call's ownretrydoes not ask for.
The retry policy
retry is false for none, a number of retries, or a policy (the type
RetryOptions), an object of these, each optional:
| Field | Default | What it is |
|---|---|---|
attempts | 2 | Retries after the first send: three sends at most. |
delay | 300 ms | The backoff's base: a random wait up to 300 ms, then up to 600, and so on. |
maxDelay | 3 s | The backoff's ceiling. |
maxRetryAfter | 3 s | The longest Retry-After honoured: an answer that asks for longer rejects at once. |
methods | GET, HEAD, OPTIONS | Which methods the client's policy retries (a call's own policy retries its call whatever its method). |
statuses | 408, 429, 502, 503, 504 | Which answers are retried, with what nobody answered. |
A live channel's retry is its
reconnects instead: a number in a row that may fail, or a policy's
attempts, delay and maxDelay, never the client's.
Responses and headers
What a TypeScript SDK method answers, how withResponse() gives its Response for the headers, and conditional reads and writes with ETags.
Receiving webhooks
OpenEmail's webhooks with the TypeScript SDK, end to end: register a hook, verify and parse what it sends, answer it, recover from failures, test it.