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.
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.
- Manage keys and access
Who creates a key, what it may reach, when it expires and how to rename, disable or delete it.
- Import in batches
The contract every import shares: batches, the dry run, replays without duplicates and the report.
- 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.
- Move an existing shop
Bring your catalogue, your sales history and your domain to a new shop, and check each step.
- AI inside your software
A reasoning step added to a screen of your own software, launched through the API and read back.
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.