@polyweave/errors (1.0.8)
Installation
@polyweave:registry=https://hub.kl1.tenere.ai/api/packages/Polyweave/npm/npm install @polyweave/errors@1.0.8"@polyweave/errors": "1.0.8"About this package
@polyweave/errors
Standardized error code normalization and HTTP-to-error mapping for Polyweave providers and adapters.
Synopsis
import {
ErrorCode,
normalizeErrorCode,
normalizeRateLimit,
parseRetryAfterSeconds,
buildErrorMetadata,
mapHttpStatusToErrorCode,
isRetryableErrorCode
} from '@polyweave/errors';
const code = normalizeErrorCode('RATE_LIMITED');
// => ErrorCode.RATE_LIMIT_EXCEEDED
const seconds = parseRetryAfterSeconds('120');
// => 120
const meta = buildErrorMetadata({
provider: 'openai',
statusCode: 429,
errorType: 'rate_limit',
retryAfterSeconds: 10
});
// => { provider: 'openai', status: 429, statusCode: 429, type: 'rate_limit', errorType: 'rate_limit', retryAfterSeconds: 10 }
Install
npm install @polyweave/errors
Why
Polyweave adapters receive errors from dozens of different providers, each with custom error shapes and status codes. This package normalizes them into canonical ErrorCode values, maps HTTP statuses to standard codes, and provides retry-awareness — so adapters and wrappers can handle errors uniformly without provider-specific logic.
API
ErrorCode
Re-exported from @polyweave/core. Enum of canonical Polyweave error codes.
| Value | Description |
|---|---|
RATE_LIMIT_EXCEEDED |
Provider rate limit hit |
QUEUE_TIMEOUT |
Request timed out in queue |
INVALID_INPUT |
Malformed or invalid request |
AUTHENTICATION_ERROR |
Missing or invalid credentials |
AUTHORIZATION_ERROR |
Permission denied |
JOB_NOT_FOUND |
Referenced resource not found |
SERVICE_UNAVAILABLE |
Provider down / overloaded |
PROVIDER_ERROR |
Generic provider-side failure |
PROTOCOL_ERROR |
Connection / transport failure |
ADAPTER_ERROR |
Internal adapter failure (fallback) |
QUOTA_EXCEEDED |
Account quota exhausted |
normalizeErrorCode(code)
normalizeErrorCode(code: string | ErrorCode | null | undefined | false): ErrorCode
Accepts raw error code strings, legacy aliases, ErrorCode enum values, or falsy input and returns the canonical ErrorCode.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
code |
string|ErrorCode|null|undefined|false |
yes | — | Raw code or alias to normalize |
Return value: Canonical ErrorCode enum value.
Aliases resolved:
| Input alias | Canonical |
|---|---|
'RATE_LIMITED', 'RATE_LIMIT_ERROR' |
RATE_LIMIT_EXCEEDED |
'TIMEOUT', 'TIMEOUT_ERROR' |
QUEUE_TIMEOUT |
'VALIDATION_ERROR' |
INVALID_INPUT |
'AUTH_ERROR' |
AUTHENTICATION_ERROR |
'FORBIDDEN', 'PERMISSION_DENIED' |
AUTHORIZATION_ERROR |
'NOT_FOUND' |
JOB_NOT_FOUND |
'CONNECTION_ERROR' |
PROTOCOL_ERROR |
'UNKNOWN' |
ADAPTER_ERROR |
Error conditions: Returns ErrorCode.ADAPTER_ERROR when code is falsy or unrecognized — never throws.
normalizeRateLimit(rateLimit)
normalizeRateLimit(rateLimit: Object | null | undefined): Object | null
Strips null and undefined values from a provider rate-limit object. Returns the cleaned object, or null if all fields were stripped.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
rateLimit |
Object|null|undefined |
yes | — | Provider rate-limit response object |
Return value: Cleaned object (only non-null/undefined keys) or null.
parseRetryAfterSeconds(value)
parseRetryAfterSeconds(value: string | number | null | undefined): number | null
Parses an HTTP Retry-After header value into delay seconds. Handles numeric seconds, HTTP-date strings (RFC 2822), and ISO dates.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
value |
string|number|null|undefined |
yes | — | Retry-After header value |
Return value: number of seconds to wait (always >= 0), or null if unparseable/falsy.
Error conditions: Returns null on:
- Falsy or empty-string input
- Non-finite number
- Unparseable date string
buildErrorMetadata(options)
buildErrorMetadata(options: {
provider?: string,
statusCode?: number,
errorType?: string,
errorCode?: ErrorCode,
originalFrameType?: string,
rateLimit?: Object,
retryAfterSeconds?: number,
requestId?: string,
originalError?: Error,
providerError?: any,
retryable?: boolean
}): Object
Builds a sanitized metadata object for error frames. All keys are optional. Only non-null/non-undefined values are included. If rateLimit is provided and non-empty after cleaning, it is included.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
options.provider |
string |
no | — | Provider name |
options.statusCode |
number |
no | — | HTTP status code (also stored as status) |
options.errorType |
string |
no | — | Provider error type string (also stored as type) |
options.errorCode |
ErrorCode |
no | — | Canonical error code |
options.originalFrameType |
string |
no | — | Frame type of the request that failed |
options.rateLimit |
Object |
no | — | Rate limit response data |
options.retryAfterSeconds |
number |
no | — | Seconds until retry |
options.requestId |
string |
no | — | Provider request ID |
options.originalError |
Error |
no | — | Original error object |
options.providerError |
any |
no | — | Raw provider error payload |
options.retryable |
boolean |
no | — | Whether the error is retryable |
Return value: Plain object with only populated keys.
mapHttpStatusToErrorCode(status)
mapHttpStatusToErrorCode(status: number): ErrorCode
Maps an HTTP status code to a canonical ErrorCode.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
status |
number |
yes | — | HTTP response status code |
| HTTP status | ErrorCode |
|---|---|
| 400, 409, 422 | INVALID_INPUT |
| 401 | AUTHENTICATION_ERROR |
| 403 | AUTHORIZATION_ERROR |
| 404 | JOB_NOT_FOUND |
| 408, 504 | QUEUE_TIMEOUT |
| 429 | RATE_LIMIT_EXCEEDED |
| 500, 502 | PROVIDER_ERROR |
| 503, 529 | SERVICE_UNAVAILABLE |
| All others | PROVIDER_ERROR |
isRetryableErrorCode(code)
isRetryableErrorCode(code: string | ErrorCode): boolean
Returns true if the normalized error code represents a transient failure suitable for automatic retry.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
code |
string|ErrorCode |
yes | — | Error code to check |
Retryable codes: RATE_LIMIT_EXCEEDED, QUEUE_TIMEOUT, SERVICE_UNAVAILABLE, PROVIDER_ERROR, PROTOCOL_ERROR.
Tests
npm test
Tests cover alias resolution for all known aliases, HTTP status mapping for all handled status codes, retryable-code classification, Retry-After header parsing (numeric, date-string, ISO, and invalid inputs), rate limit object cleaning, and metadata construction with various field combinations.
Requirements
Node.js 22 or later. ESM only. Peer-depends on @polyweave/core.
Dependencies
Development Dependencies
| ID | Version |
|---|---|
| @rigor/core | * |
Peer Dependencies
| ID | Version |
|---|---|
| @polyweave/core | * |