API reference

Errors

Every error answer has the same JSON shape. Act on its error code. The HTTP status tells you the kind of problem, and the code tells you exactly which one.

The shape of an error

JSONAnswer 422
{
  "error": "validation_failed",
  "message": "The request does not match the schema.",
  "request_id": "req_00000000000000000000000000000000",
  "details": [
    {
      "field": "/name",
      "problem": "required"
    }
  ]
}
  • error is the code to act on. It never changes for a given problem.
  • message is for people. Don't parse it, because its wording may change.
  • request_id identifies the request. Quote it if you write to Uncart about one.
  • details comes only with validation_failed. Each entry names a field, as a JSON pointer into the body or as query.<name>, and the rule it broke. It never repeats the value you sent.

Every error code

CodeStatusWhen
unauthorized401No valid API key. Every refusal of a key (missing, malformed, unknown, revoked, expired, the wrong mode or a missing scope) gets this same answer, so it tells nobody why.
forbidden403The key is valid, but its shop does not connect through the Uncart API.
origin_not_allowed403A storefront request came from a page that is not https on one of the shop's verified domains, exactly, or named none (Origin). Nothing was done.
busy503Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds.
not_found404Nothing is at this address, or the shop has no such object.
feature_off404The shop does not offer this web component now: it is not switched on (dashboard, Shop setup, Connection), there is no WhatsApp number to open, prices without tax for price drops, or, with a live key, the shop is not live yet.
method_not_allowed405The address exists, but not with this method.
invalid_json400The body is not JSON.
invalid_request400A header or the address is not as documented.
unsupported_media_type415A body was sent that is not application/json.
body_too_large413The body is over 1 MB.
validation_failed422The body or the query does not match the schema. details names each field and the rule it broke, never its value.
idempotency_key_required400This write needs an Idempotency-Key header.
idempotency_key_reused422This Idempotency-Key was used in the last 24 hours with another method, address or body.
idempotency_in_progress409A request with this Idempotency-Key is still being handled. Try again after Retry-After seconds.
conflict409What you sent conflicts with what Uncart holds (for example, an id another object of the shop already uses). Nothing was changed.
rate_limited429Too many requests with this key. Try again after Retry-After seconds.
internal_error500Something went wrong on Uncart's side. Nothing the request did is kept, nor its answer: send the same request again, with the same Idempotency-Key, and it runs once.

Uncart may add codes. Treat a code you don't know by its HTTP status.

Which errors to retry

Wait for the seconds in the Retry-After header, then send the same request again with the same Idempotency-Key, after 429 rate_limited, 503 busy and 409 idempotency_in_progress.

A 500 internal_error means something failed on Uncart's side. Uncart doesn't keep that answer for the Idempotency-Key. A request sent again runs again. Before you send a write again after a 500, check whether it took effect.

The other errors come from the request itself, and sending it again unchanged gets the same answer.

Every key problem is one answer

A missing key, a mistyped one, a revoked or expired key, a test key on live data and a key without the scope all get the same 401 unauthorized. Uncart gives all of them one answer, so it tells someone guessing keys nothing. Check the key's prefix first, then its scopes, then the Authorization header.

JSONAnswer 401
{
  "error": "unauthorized",
  "message": "A valid API key is needed, in the Authorization header.",
  "request_id": "req_00000000000000000000000000000000"
}