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
{
"error": "validation_failed",
"message": "The request does not match the schema.",
"request_id": "req_00000000000000000000000000000000",
"details": [
{
"field": "/name",
"problem": "required"
}
]
}
erroris the code to act on. It never changes for a given problem.messageis for people. Don't parse it, because its wording may change.request_ididentifies the request. Quote it if you write to Uncart about one.detailscomes only withvalidation_failed. Each entry names a field, as a JSON pointer into the body or asquery.<name>, and the rule it broke. It never repeats the value you sent.
Every error code
| Code | Status | When |
|---|---|---|
unauthorized | 401 | No 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. |
forbidden | 403 | The key is valid, but its shop does not connect through the Uncart API. |
origin_not_allowed | 403 | A 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. |
busy | 503 | Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds. |
not_found | 404 | Nothing is at this address, or the shop has no such object. |
feature_off | 404 | The 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_allowed | 405 | The address exists, but not with this method. |
invalid_json | 400 | The body is not JSON. |
invalid_request | 400 | A header or the address is not as documented. |
unsupported_media_type | 415 | A body was sent that is not application/json. |
body_too_large | 413 | The body is over 1 MB. |
validation_failed | 422 | The body or the query does not match the schema. details names each field and the rule it broke, never its value. |
idempotency_key_required | 400 | This write needs an Idempotency-Key header. |
idempotency_key_reused | 422 | This Idempotency-Key was used in the last 24 hours with another method, address or body. |
idempotency_in_progress | 409 | A request with this Idempotency-Key is still being handled. Try again after Retry-After seconds. |
conflict | 409 | What you sent conflicts with what Uncart holds (for example, an id another object of the shop already uses). Nothing was changed. |
rate_limited | 429 | Too many requests with this key. Try again after Retry-After seconds. |
internal_error | 500 | Something 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.
{
"error": "unauthorized",
"message": "A valid API key is needed, in the Authorization header.",
"request_id": "req_00000000000000000000000000000000"
}