Pagination, filters, and errors

Nasam lists use the response shape defined by each operation. A paginated read includes its named collection and a pagination object. For GET /v1/products, the surrounding object has products, categories, filterCounts, and pagination:

{
  "products": [],
  "categories": [],
  "filterCounts": {},
  "pagination": { "page": 1, "limit": 10, "total": 73, "totalPages": 8 }
}

The empty collections above show the envelope, not a real result with total: 73. Start at page=1, keep the same filters and sort, and continue while page < totalPages. The meaning and limits of page and limit vary by operation. Products default to 10 and cap limit at 100; the inventory forecast defaults to 25 and also caps at 100. Brand discovery returns the full accessible set when limit is omitted. Other reads return a whole array or object without a pagination member. Follow the operation's response schema instead of assuming a universal envelope or cursor.

For a repeatable catalog sync, choose a fixed limit, filters, and sort. Process the named collection on each page, increment page, and stop after the response's totalPages. If the source changes during traversal, a later run should reconcile records by stable resource ID; page numbers alone are not a change log. Do not reuse a totalPages value across different filters or later sync runs.

Encode each filter as its operation specifies

Examples of supported wire formats:

GET /v1/products?brandIds=20,21&page=1&limit=25
GET /v1/orders?statuses=Created,Packed&fulfillmentModel=Seller
GET /v1/vendor/purchase-orders?brandIds=20&brandIds=21&statuses=Confirmed&statuses=Closed

The product and order DTOs split these list filters on commas. Other routes differ: for Brand Health category names, send repeated categories keys, because a category can contain a comma. Vendor purchase-order filters accept repeated values for brandIds, saleChannelIds, and statuses. Consult the operation reference for each query. Reuse the same filter values between a page read and its companion count or export only where their parameter schemas agree.

The export endpoint for vendor purchase orders is a separate contract and uses comma-separated values. Build query encoders per operation rather than sharing one encoder across a page read and an export. If a filter has no effect, inspect the exact wire format first; avoid broadening the request and silently syncing unrelated brands.

Validation and errors

DTO-validated inputs reject unknown fields. Send only documented fields and use the exact type and case shown in the operation page. A typical non-2xx JSON response contains statusCode, message, and path; an exception may add fields:

{
  "statusCode": 400,
  "message": "Validation failed",
  "path": "/v1/products?page=0"
}

This example illustrates the envelope; the exact message depends on the exception. Branch on HTTP status and documented response fields, not a localized message. A 403 can mean the key lacks a grant or a requested brand lies outside its scope. A 404 can also hide a resource the caller cannot access. For transient failures, use backoff; before retrying a write, determine whether its first attempt took effect. Batch writes such as packing orders can report failures per item inside a successful HTTP response, so inspect the whole result.

No fixed request quota, rate-limit header, or Retry-After behavior is specified. If you receive HTTP 429, retry safely with backoff. Do not hard-code an undocumented quota.

Result	Client action
2xx list response	Read the operation's named collection and pagination; an empty page is not an HTTP failure.
400	Fix field names, types, enum case, or filter encoding before repeating.
401	Check the key being sent and its rotation state.
403 or 404	Check grant, brand scope, and resource ID; do not infer another brand's existence.
409	Re-read the resource and resolve the state conflict before writing again.
429 or 5xx	Back off; for writes, inspect current state before deciding whether a retry is safe.

For a multi-item write, use the operation's per-item result to decide which items need attention. A successful HTTP response can still contain item failures, and resubmitting the whole batch can repeat items that already succeeded.