Errors and retries

The SDK's error object, its error types, and how automatic retries work, so API and network failures come back as values you can check.

The error object

When a call fails, error is a plain CossError object (never an exception):

Include request_id when contacting support. issues lists per-field problems of a validation_error.

const {  } = await ..({
  : "Acme <hello@acme.com>",
  : "user@example.com",
  : "",
  : "Hi!",
});

if (?. === "validation_error") {
  for (const  of . ?? []) .(., .);
}

Error types

connection_error and timeout_error happen on the client, so their status and request_id are null.

Automatic retries

The SDK retries up to maxRetries times (default 2) on connection errors, timeouts, and 409, 429 and 5xx responses. Other errors are returned immediately.

  • The wait grows exponentially (500 ms, 1 s, 2 s, … up to 8 s) with random jitter.
  • A Retry-After header is honored exactly; if it asks for more than 60 s, the error is returned instead.
  • Every POST carries an Idempotency-Key that is reused on each retry, so a retried send is never delivered twice.

Last updated