CartDocs

Pagination, errors and limits

Paid plans

Page through lists with a cursor, read error codes, stay within the rate limit and send POST calls safely with an Idempotency-Key.

On this page

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_here

The 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_here

On 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.

StatusCodeMeaning
400bad_request, unsupported_version, invalid_cursorThe call itself is malformed.
401unauthenticatedNo key, or a wrong, expired or revoked key.
403forbiddenThe key lacks the permission.
403feature_not_availableYour plan does not include this.
404not_foundThe object does not exist, or not in your shop.
405method_not_allowedThe path exists, but not with this method.
409conflict, idempotency_in_flightThe object's state does not allow this now, or the same call is still running.
422validation_failed, idempotency_mismatchA field is wrong, or an Idempotency-Key was reused for another call.
429rate_limitedToo many calls. Wait and try again.
500server_errorSomething broke on our side.
503unavailableThe 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 422 idempotency_mismatch.
  • If the first call is still running, you get 409 idempotency_in_flight. Wait a moment and send it again.
  • A POST without the header gets 400.

Updated 13 November 2026