Developers ยท Guides

Handle every refusal and retry without duplicates

A failed call to the API of Ultineo E-commerce uses the same envelope as a successful one: read the HTTP status code, then the message in response. This guide sorts the statuses by what each asks of your client.

What to know before you handle errors

One envelope, also on failure

A refusal carries the three keys of every answer, code, title and response, and its response is a string that says what went wrong. The page "API conventions" describes the envelope.

The status code decides

Messages are stable English sentences that you can log and show to an operator. Base your logic on the status code, not on the wording of a message.

Limits on every request

A request body is no larger than 200,000 bytes, and each resource has its own batch limit, from 25 to 500 items. A larger body is answered with 413 and an import batch over the limit with 422: send smaller batches.

Handle an answer in this order

1

Read the status first

Read the HTTP status code first, then read response: the record or the import report on success, an explanatory message on failure.

2

Correct a malformed request

A 400 means that the body is not valid JSON, or that a read gave neither the key of the record nor its id. A 422 on the whole call means that items is missing, empty or over the batch limit, or that every item was refused.

3

Check key and scopes

A 401 means that no key was sent, that the Authorization header does not start with Bearer, or that the key has expired. A 403 means an unknown or disabled key, a missing scope, or a key used for another shop.

4

Check record and path

A 404 means that the record does not exist in your shop, or that the path does not exist. Check the spelling of the reference, then the path against the endpoint tables.

5

Retry what can be retried

A 429, a 503, a dropped connection or a refused item with code 409 or 500 can all be retried. Wait a few seconds between retries, and honour Retry-After when it is present.

6

Go through the refused items

In a report, each refused item carries its own code. A 422 asks you to correct the item, a 404 to import first the record it refers to, a 409 to retry it later, a 500 to send it again.

A refused call and a refused item

The first sample is a call refused for a missing scope: the envelope, with a message in response. The second is one refused item: an entry of the data list of the import report, while the other items of the batch carry on.

Refused call

{
  "code": 403,
  "title": "Forbidden",
  "response": "The API key is missing the required scope: order:write"
}

Your client acts on the status code, 403, and the message names the missing scope.

Refused item

{
  "index": 3,
  "external_id": "SHP-20931",
  "action": "refused",
  "id": null,
  "code": 409,
  "title": "Conflict",
  "reason": "Another import is already writing this shipment.",
  "notice": []
}

The entry gives the position of the item in index and the status of its refusal in code and title; here reason reports a 409, an item to retry later.

Three answers to plan for

A 301 on a call

A 301 means that you called http://. Repeat the call on https://, and call that address directly from then on: the guide "Make your first API call" says what a plaintext request discloses.

A 429 or a 503

Too many requests in a short time are answered with 429, and a 503 means that the service is temporarily unable to handle this resource for your shop. On a 429, wait for the number of seconds given in the Retry-After header, then retry; on a 503, retry later.

A 409 conflict

On an import, a 409 means that the same record is already being imported by another request, or that a voucher code is already taken: retry the item later, or choose another code. On the parcel and address routes, a 409 means that the tracking number or the contact is already held, and the answer carries the id of the record that holds it.

The articles behind this page

This page restates the following articles of the help center. They hold every field, every value and every answer.

Error codes

API overview

Your first API call

Import & export

Make bulk catalogue changes with a readable result

Open the page

Product pages to read next

API access

Connect your systems through scoped shop access

Import & export

Make bulk catalogue changes with a readable result

Orders

Items, payments and shipments together

Promo codes

Codes, validity dates and usage limits

Continue in this section

Make your first API call

The address, the health check, the key in the header and how to read the answer of a first call.

Open the page

Manage keys and access

Who creates a key, what it may reach, when it expires and how to rename, disable or delete it.

Open the page

Import in batches

The contract every import shares: batches, the dry run, replays without duplicates and the report.

Open the page

Connect an ERP or a supplier feed

A typical connection from another system: the keys to map, a first dry run, the sync and its checks.

Open the page

Move an existing shop

Bring your catalogue, your sales history and your domain to a new shop, and check each step.

Open the page

AI inside your software

A reasoning step added to a screen of your own software, launched through the API and read back.

Open the page

Developer overview

Connect your shop once it is open

Each application to open a shop is reviewed by our team, which replies by e-mail.

Questions

Yes. Every import is recognized record by record, so sending the same batch again never creates a duplicate. Records already saved come back as unchanged.

An import checks each item on its own. The batch answers 200 when at least one item was created, updated or left unchanged, even if others were refused, and 422 when every item was refused, with the same report so that you can see why.

The message "The API key doesnโ€™t have permissions to perform the request." covers three cases without telling them apart: an unknown key, a disabled key and a key whose shop is no longer active. An expired key answers 401 instead, with its own message. The guide "Manage keys and access" says why the answer is the same.

The method is not supported on that path: the message reads "The parameters were valid but the request failed." Only GET and POST are served, plus PATCH and DELETE on the parcel and address routes.