Pagination, errors and limits
Paid plansPage through lists with a cursor, read error codes, stay within the rate limit and send POST calls safely with an Idempotency-Key.
These rules apply to every part of the API. Build them into your client once and every call benefits.
Pages of a list
Lists come in pages, newest first. Set the page size with limit: 25 by default, 100 at most.
GET /api/v1/orders?limit=50 HTTP/1.1
Host: api.ixxocart.com
Authorization: Bearer ics_your_key_hereThe meta of the answer says whether there is more:
{
"data": [ ... ],
"meta": { "next_cursor": "eyJzb3J0X2tleSI6...", "has_more": true, "limit": 50 },
"errors": []
}To get the next page, send the same call with cursor set to next_cursor:
GET /api/v1/orders?limit=50&cursor=eyJzb3J0X2tleSI6... HTTP/1.1
Host: api.ixxocart.com
Authorization: Bearer ics_your_key_hereOn the last page has_more is false and next_cursor is null. Keep the other filters the same while you page. A cursor that cannot be read gets 400 with invalid_cursor.
Errors
An error answer has data: null and one or more entries in errors:
{
"data": null,
"meta": {},
"errors": [
{ "code": "validation_failed", "message": "The price must be 0 or more.", "field": "price_minor" }
]
}Use the code in your program; the message is for people and may change. field names the field at fault when there is one. A failed check of several fields lists one error per field.
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request, unsupported_version, invalid_cursor | The call itself is malformed. |
| 401 | unauthenticated | No key, or a wrong, expired or revoked key. |
| 403 | forbidden | The key lacks the permission. |
| 403 | feature_not_available | Your plan does not include this. |
| 404 | not_found | The object does not exist, or not in your shop. |
| 405 | method_not_allowed | The path exists, but not with this method. |
| 409 | conflict, idempotency_in_flight | The object's state does not allow this now, or the same call is still running. |
| 422 | validation_failed, idempotency_mismatch | A field is wrong, or an Idempotency-Key was reused for another call. |
| 429 | rate_limited | Too many calls. Wait and try again. |
| 500 | server_error | Something broke on our side. |
| 503 | unavailable | The service is briefly unavailable. Try again later. |
Some calls have their own codes, for example orders.not_found or orders.part_already_paid. The OpenAPI description lists them per call (see The IXXO Cart REST API).
Rate limits
Each key may make 60 calls a minute, with short bursts allowed. Every answer says where you stand:
RateLimit-Limit: the calls allowed.RateLimit-Remaining: the calls left now.RateLimit-Reset: the seconds until your full allowance is back.
Over the limit, you get 429 with rate_limited and a Retry-After header with the seconds to wait. Slow down when RateLimit-Remaining gets low rather than waiting for a 429.
Send POST calls safely
A network hiccup can leave you unsure whether a POST went through. Sending it again could create a second order or a second refund. To prevent this, every POST call needs an Idempotency-Key header: any unique text of up to 255 characters, for example a UUID.
POST /api/v1/orders/ord_.../notes HTTP/1.1
Host: api.ixxocart.com
Authorization: Bearer ics_your_key_here
Content-Type: application/json
Idempotency-Key: 6f1c2d3e-8a9b-4c5d-9e0f-1a2b3c4d5e6f
{ "body": "Customer asked for gift wrapping." }If the call is sent again with the same key and the same body, you get the first answer back, with the header Idempotent-Replayed: true, and nothing happens twice.
- Use a new key for each new action, and the same key only when you repeat the same call.
- A key is remembered for 24 hours.
- The same key with another body or path gets
422idempotency_mismatch. - If the first call is still running, you get
409idempotency_in_flight. Wait a moment and send it again. - A POST without the header gets
400.
Related
Updated 13 November 2026