@sp-api-sdk/common

Common library for the Amazon Selling Partner API (SP-API) SDK: Axios factory, regions, rate limiting and errors

Installing

npm install @sp-api-sdk/common

Note: You typically do not need to install this package directly. It is automatically included as a dependency of every API client package.

Overview

This package provides the shared infrastructure used by all API client packages:

• Axios instance factory with authentication, rate limiting, logging, and error handling
• Region configuration for NA, EU, and FE endpoints (production and sandbox)
• Error handling with SellingPartnerApiError

Client Configuration

The ClientConfiguration interface is used by all API client constructors:

import {type ClientConfiguration} from '@sp-api-sdk/common'

| Option | Type | Required | Description | | --------------------- | ----------------------- | -------- | ----------------------------------------------- | | auth | SellingPartnerApiAuth | Yes | Authentication instance from @sp-api-sdk/auth | | region | 'na' \| 'eu' \| 'fe' | Yes | Selling Partner API region | | sandbox | boolean | No | Use sandbox endpoints (default: false) | | rateLimiting | object | No | Rate limiting retry configuration | | logging | object | No | Request/response/error logging configuration | | restrictedDataToken | string | No | Restricted Data Token for accessing PII | | userAgent | string | No | Custom user-agent header |

Regions

Three regions are supported, each with production and sandbox endpoints:

| Region | Code | Production Endpoint | | ------------- | ---- | ----------------------------------------- | | North America | na | https://sellingpartnerapi-na.amazon.com | | Europe | eu | https://sellingpartnerapi-eu.amazon.com | | Far East | fe | https://sellingpartnerapi-fe.amazon.com |

When sandbox is set to true, the sandbox variant of the endpoint is used (e.g. https://sandbox.sellingpartnerapi-eu.amazon.com).

Rate Limiting

When rateLimiting.retry is enabled, the SDK automatically retries HTTP 429 responses. The retry delay is calculated as follows:

1. If the response includes an x-amzn-ratelimit-limit header, the delay is derived from it.
2. Otherwise, the SDK falls back to the documented rate limits for the specific endpoint.
3. If no rate limit information is available, a 60-second default delay is used.

You can optionally provide an onRetry callback to be notified on every retry:

rateLimiting: {
  retry: true,
  onRetry: ({delay, rateLimit, retryCount, error}) => {
    console.log(`Retry #${retryCount}, waiting ${delay}ms (rate limit: ${rateLimit})`)
  },
}

Logging

Logging is powered by axios-logger and can be configured independently for requests, responses, and errors:

logging: {
  request: true,   // or a RequestLogConfig object
  response: true,  // or a ResponseLogConfig object
  error: true,     // or an ErrorLogConfig object
}

Pass true to use sensible defaults (no headers logged for requests, headers logged for responses). Pass a configuration object to customize the behavior.

By default, request and response loggers use console.info, and the error logger uses console.error.

Warning: Enabling headers: true in the request logger will log authentication tokens. This should be disabled in production.

Error Handling

API errors are wrapped in SellingPartnerApiError, which extends AxiosError and adds context:

import {getMarketplaceByCode} from '@bizon/amazon-ids'
import {SellingPartnerApiError} from '@sp-api-sdk/common'

const de = getMarketplaceByCode('de')!

try {
  await client.searchOrders({marketplaceIds: [de.id]})
} catch (error) {
  if (error instanceof SellingPartnerApiError) {
    console.error(error.message) // e.g. "orders (2026-01-01) error: Response code 403"
    console.error(error.apiName) // e.g. "orders"
    console.error(error.apiVersion) // e.g. "2026-01-01"
    console.error(error.innerMessage) // Original axios error message
  }
}

License

MIT

Miscellaneous

    ╚⊙ ⊙╝
  ╚═(███)═╝
 ╚═(███)═╝
╚═(███)═╝
 ╚═(███)═╝
  ╚═(███)═╝
   ╚═(███)═╝