Error Handling

When interacting with our API, various error responses may be returned depending on the nature of the request and the current system state. This section outlines how to interpret and troubleshoot the most common HTTP error codes.

All endpoints return standard HTTP status codes to indicate the success or failure of an API request. When a request fails, the response typically includes a JSON object with additional details, such as the error message, a code, and where applicable, information about which fields caused the error.

Understanding these errors can help you quickly resolve issues and improve the stability of your integration.

Common HTTP Error Codes

Though most errors are self explanatory and contain textual information on the reason of the failure. Most cases can be resolved through timed retries.

It is strongly advised to avoid spamming the API while retrying, and to prefer implementing delays until resolution.

Some cases (e.g. 406/409/415) should however trigger a resolution requirement instead of retries.

General data read operations should self resolve over time (quotas, availability), while write operations should be stopped after a reasonnable amount of retries and considered failed.

Pagination

To efficiently handle large datasets and improve performance, our API implements pagination on endpoints that return lists of resources. Depending on the endpoint, pagination is handled using either:

• Page-based pagination (with pageIndex and pageSize in the query parameters)

• Cursor-based pagination (with cursor tokens provided in the Link header)

This section explains how each method works and how to properly implement them in your integration.

Page-Based Pagination

This method uses pageIndex (starting from 1) and pageSize to navigate through a dataset.

Example Request

GET /brands?pageIndex=1&pageSize=100

Query Parameters

Cursor-Based Pagination

Cursor-based pagination is more efficient and reliable for large or dynamic datasets. The client uses a cursor token provided in the response to retrieve pages.

How It Works

• The API returns pagination links in the Link header.

• Each link has a rel attribute: first, prev, next, etc.

• Use the cursor parameter from the link to fetch pages.

Example Header

Link: 
; rel="first",
; rel="prev",
; rel="next"

Example Request (Next Page)

GET /products?cursor=NjdjN2Y2YzUwNDI2ZTBlMjBiOWNhM2UyfG5leHQ=&limit=12&fields=*

Listing retrieval

Since our API does not currently support webhooks, your integration must poll listing endpoints (e.g. orders, returns, stock) regularly to fetch new or updated resources.

To ensure you don’t miss data, and don’t overload the API, please follow these guidelines:

1. Use pagination and filters

• Never try to retrieve everything in one call.

• Always use limit and cursor parameters (or equivalent) to navigate through paginated results.

• When available, use updatedAtMin to fetch only what changed since your last poll.

2. Poll at reasonable intervals

• Adjust polling frequency based on how fast data changes (e.g. every 5–10 minutes for orders).

• Don’t call multiple endpoints simultaneously — stagger your polls.

• Avoid polling too frequently to prevent reaching rate limits.

3. Ensure reliable processing

• Always log the cursor or lastUpdatedAt of the last processed page.

• Retry failed calls with exponential backoff (on 5xx errors or timeouts).

• Use unique resource IDs (e.g. orderId) to prevent duplicate processing.

4. Combine snapshot & incremental strategies

For critical flows like order ingestion:

• Run regular full snapshots (e.g. once a day).

• Between snapshots, use incremental polling with updatedAtMin.

• This helps detect missed updates (e.g. status changes, late orders).

Common Pitfalls

Example (JS-like pseudocode)

let lastFetchedAt = '2024-10-01T00:00:00Z';
function pollOrders() {
  let cursor = null;
  do {
    const res = fetch(`/outbound-shipments?limit=100&cursor=${cursor}&updatedAtMin=${lastFetchedAt}`);
    process(res.items);
    cursor = res.nextCursor;
  } while (cursor);
  lastFetchedAt = now();
}
setInterval(pollOrders, 300000); // every 5 minutes

Rate Limiting / Quotas

Why we apply rate limits

To ensure stability, fair usage, and optimal performance for all partners, Octopia APIs enforce rate limits on certain endpoints. These limits prevent abuse, ensure equitable access, and protect our systems during high-load periods.

How it works

• Rate limits are enforced per endpoint, per seller ID, and per client application (client_id).

• The limits are evaluated over a rolling one-hour window.

• If a client exceeds the allowed threshold for a given route, a 403 Forbidden error is returned with the message:

{
  "status": 403,
  "title": "Quota exceeded",
  "detail": "You have exceeded the hourly quota for this endpoint."
}

Each API call is counted against both the client_id and the sellerId used in the request.

If you manage multiple seller accounts under a single integration:

• You can call the same endpoint multiple times for different sellers without exceeding the quota, as each sellerId has an independent limit.

• For example, calling a route 500 times for sellerId=10001 does not block your next call to the same route with sellerId=10002.

Although we do not expose the exact quota values per route (for security reasons), we recommend the following:

• Avoid unnecessary polling: Use updatedAtMin/Max filters and pagination to fetch only what’s needed.

• Distribute your calls: Spread API calls evenly over time rather than batching all at once at the top of the hour.

• Use sellerId-aware logic: If your system handles multiple sellers, treat their usage independently — don’t artificially throttle all traffic based on one seller’s activity.

• Implement exponential backoff: On receiving a 403 quota error, pause for a short time and retry progressively less frequently (e.g., wait 60s → 120s → 300s).

• Log and monitor quota errors: Capture 403 errors in your logs to detect patterns or misbehaving loops.

What happens when the quota is exceeded?

• A 403 response is immediately returned.

• No partial processing is done — the call is fully rejected.

• You should not retry immediately. Doing so may result in further denials or temporary blocks.

What is the exact quota/rate for endpoint X ?

Quotas are implemented as a security measure, they are tailored to suit most usecases and are high enough to avoid being reached. Exact values are not communicated.

Asynchronous quota errors

Offer and Product submission is subjected to ressource quantity quotas.

Those quotas are not API related and are configured at the seller account level, are set to low values for new accounts and automatically upgraded based on data submission quality.

Quota depletion is stated in integration reports. Replenishment is hourly.

Data Formats

Date / Time Formats

All dates and times in the API follow the ISO 8601 standard in UTC timezone unless stated otherwise.

Format

YYYY-MM-DDTHH:MM:SS.sssZ

Examples

"2025-10-20T14:30:00Z"
"2023-03-30T15:28:58.9275688+00:00"

IDs / GTINs / SKUs

UUIDs

Many identifiers follow the UUID v4 format (e.g. outboundShipmentId, returnId, productId, parcelId, etc.)

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

GTINs

GTIN (Global Trade Item Number) must be numeric and between 8 and 14 digits.

^\d{8,14}$

Example:

"gtin": "1234567890123"

SellerProductReference

This is your internal product reference. It must be:

• Unique per seller per product-condition combination

• Between 1 and 40 characters

• Alphanumeric, with optional underscores or dashes

• Case-sensitive

Examples:

"sellerProductReference": "SKU-12345-BLUE"
"sellerProductReference": "IPHONEX_NEW"

Character Sets & Encoding

All payloads (request and response bodies) use UTF-8 encoding.

XML payloads (for Offers zip packages)

• Your offers.xml or products.xml should declare:

xml version="1.0" encoding="utf-8"

• Special characters in text nodes (e.g. &, <, ") must be escaped using standard XML escaping.

Validation Hints

Delivery / Logistics

Octopia provides a base set of delivery modes as follows :

Small parcels

Large parcels

Extended Delivery Modes and Legacy matching

Based on your activities on our platform and your active subscriptions other deliverymodes can be returned or submitted.

Please see below the table for additional details.

Footnotes :
* : depends on SalesChannel choice for enabled delivery modes
(1) : These delivery codes are used in the legacy SOAP API
(2) : Delivery modes marked as “Cdiscount” are only available on the CDISFR salesChannel, offers with such delivery modes will not be published on other salesChannels

All values are case sensitive

Depending on your activity within the Octopia network and the complexity of your fulfillment management with our services, other delivery modes can be read from the GET /orders endpoint.

Previously available modes, which are currently considered obsolete are not given in this mapping table.

Columns explanations

Octopia – Code

Octopia Code is the delivery mode short code range, available through APIs exposing the “code” or “mode” attribute

Offer Endpoint

• GET /offers

/* items[].deliveryOffers[] */
"deliveryModes": [
  {
    /* other information */
    "code": "THD"
  }
]

Fulfillment Endpoint

• GET /outbound-shipments

/* items[] */
"delivery": [
  {
    "mode": "THD"
    /* other information */
  }
]

It is also the required value when submitting data through

• POST /offer-requests (please note that submitting offers with this endpoint does not publish towards Cdiscount)

• POST /outbound-shipments

Octopia – Label

The delivery mode attribute “label” or “mode” is available through the following APIs :

Orders Endpoint

• GET /orders

/* items[].lines[] */
"delivery": [
  {
    "mode": "TrackedHomeDelivery"
    /* other information */
  }
]

Please note that PickupPoint delivery modes also expose pickupIp and pickupName within shippingAddresses nodes.

LegacyMode

The delivery mode attribute “ModLiv” was available through the following APIs :

• SOAP – GetOrderList

It is provided here as a reference mapper for legacy integrations and should not be used anymore. See also SOAP API Deprecation

XMLOfferPackage

These values are to be used in XML offer publication packages under the OfferShippingInformationList node as an “DeliveryMode” attribute to ShippingInformation.

XML Offers Endpoint

• POST /offer-integration-packages

SalesChannel Availability

Some delivery modes are currently required whichever the targetted publication channel or offer publication method

Others can only be submitted to specific sales channels.

All sales channels can accept or not your offers based on which delivery methods you provide.

OSP Name (language code)

This is how it is currently displayed within your seller portal.