@polyweave/errors (1.0.9)

Published 2026-07-11 15:24:23 +00:00 by Dvorak

Set up this registry in your project .npmrc file:

@polyweave:registry=https://hub.kl1.tenere.ai/api/packages/Polyweave/npm/

To install the package using npm, run the following command:

npm install @polyweave/errors@1.0.9

or add it to the package.json file:

"@polyweave/errors": "1.0.9"

For more information on the npm registry, see the documentation.

@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.

Development Dependencies

ID	Version
@rigor/core	*

Peer Dependencies

ID	Version
@polyweave/core	*

polyweave errors error-codes mapping

Details

npm

2026-07-11 15:24:23 +00:00

673

John Dvorak

SEE LICENSE IN LICENSE

3.8 KiB

Assets (1)

errors-1.0.9.tgz 3.8 KiB

Versions (7) View all

1.0.8

2026-07-20

1.0.9

2026-07-11

1.0.6

2026-07-11

1.0.5

2026-07-10

1.0.4