TypeScript SDK
CLI and agents
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):
| Field | Type | Description |
|---|---|---|
type | CossErrorType | The category, see Error types |
code | string | Machine-readable reason, e.g. invalid_api_key |
message | string | Human-readable explanation; may change |
status | number | null | HTTP status, null when no response was received |
request_id | string | null | The API's X-Request-Id |
param | string, optional | The request field or header the error relates to |
issues | { path: string; message: string }[], optional | Per-field validation problems |
hint | string, optional | What to try next, often with a docs URL |
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
type | Status | Meaning |
|---|---|---|
invalid_request_error | 400 / 413 / 422 | Malformed JSON, payload too large, or failed validation (issues) |
authentication_error | 401 | missing_api_key or invalid_api_key |
permission_error | 403 | The key lacks the permission (insufficient_permissions) |
not_found_error | 404 | No such resource in the key's environment |
idempotency_error | 409 / 422 | request_in_progress, or idempotency_key_reused with a different body |
rate_limit_error | 429 | Too many requests |
billing_error | 402 | usage_limit_exceeded, billing_hold, budget_exceeded, plan_limit_reached or plan_feature_unavailable (never retried; see Plans and billing) |
api_error | 5xx, other | Server error, or a response that is not a coss.com error (unexpected_response) |
connection_error | none | Network failure (network_error), or you aborted (aborted) |
timeout_error | none | An attempt exceeded timeout (request_timeout) |
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-Afterheader is honored exactly; if it asks for more than 60 s, the error is returned instead. - Every
POSTcarries anIdempotency-Keythat is reused on each retry, so a retried send is never delivered twice.
Last updated
On This Page