Skip to Content

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:

FieldWhat it is
kindhttp (the API answered a failure), network, timeout, parse (an answer that could not be read), or abort (the call's signal).
statusThe HTTP status; 0 when nothing answered.
codeThe API's error, a snake_case code such as domain_not_verified; null when the answer names none.
bodyThe 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.
retryabletrue 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.
responseThe Response, when one came: an http or a parse failure.
attemptsHow 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, 502 to 504), and on 408 and 429, with jittered backoff, and Retry-After honoured up to maxRetryAfter (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.update takes an idempotencyKey only 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.create that names a webhook (messageWebhook, eventWebhook) requires an Idempotency-Key header, 1 to 128 characters, which the API's document does not list as a parameter: send it in the call's headers ({ 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 POST whose answer was lost may have landed. It is sent once more only when the API refused it before doing anything, a 429 (a rate limit, always temporary), after the Retry-After it asks for, when that is within maxRetryAfter. A long hold (a paused sender's 429 sending_paused) is the caller's to wait out. A 503 temporary_failure is 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 retry wins over all of this: retry: false, or a policy, which vouches that sending it twice is harmless. A client made with retry: false retries nothing a call's own retry does 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:

FieldDefaultWhat it is
attempts2Retries after the first send: three sends at most.
delay300 msThe backoff's base: a random wait up to 300 ms, then up to 600, and so on.
maxDelay3 sThe backoff's ceiling.
maxRetryAfter3 sThe longest Retry-After honoured: an answer that asks for longer rejects at once.
methodsGET, HEAD, OPTIONSWhich methods the client's policy retries (a call's own policy retries its call whatever its method).
statuses408, 429, 502, 503, 504Which 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.