Errors
Format
Every error has the same format, in JSON or XML according to the chosen format:
{
"error": {
"code": "validation_error",
"internal_code": 113,
"message": "The request is invalid.",
"request_id": "req_01JC8Z…",
"details": [
{ "field": "exp_date", "issue": "Invalid ISO date", "code": "invalid_format" }
]
}
}
| Field | Description |
|---|---|
code | stable error code. Use this field in your code. |
internal_code | error number, useful when talking to support |
message | description in English, for people. It may change: do not base decisions on it |
request_id | request identifier. It also comes in the X-Request-Id header of every response |
details | when present: list of problems per field, or an object with extra information |
Talking to support
Always send the request_id. With it we find the exact request in the logs.
Codes
| HTTP | code | Internal | When it happens | What to do |
|---|---|---|---|---|
| 400 | invalid_json | 117 | the body is not valid JSON | fix the JSON |
| 401 | invalid_api_key | 101 | missing, invalid, revoked or expired key, or key sent in the URL | check the key and the header |
| 402 | subscription_inactive | 105 | the organization has no active subscription | renew the subscription |
| 403 | api_access_not_enabled | 102 | the API is not enabled for the organization | request access in the panel |
| 403 | api_access_suspended | 103 | access was suspended | contact support |
| 403 | workspace_not_eligible | 104 | the key belongs to a personal workspace | use an organization |
| 403 | insufficient_scope | 108 | the key lacks the required scope (details.required_scope) | use a key with the right scope |
| 403 | terms_not_accepted | 130 | the deadline to accept the new version of the terms has passed | the owner or an admin accepts the terms in the panel |
| 404 | not_found | 110 | route, item or id does not exist, or the item belongs to another organization | check the id |
| 406 | not_acceptable | 115 | Accept asks for a format other than JSON or XML | use JSON or XML |
| 409 | conflict | 128 | the id sent in a POST already exists | use another id or fetch the item |
| 409 | store_has_products | 111 | deleting a store with products without cascade=true (details has the counts) | see Stores |
| 409 | idempotency_in_progress | 129 | the same Idempotency-Key is still being processed | wait for Retry-After and retry |
| 412 | precondition_failed | 112 | If-Match does not match the current version (the current ETag comes in the response) | read the item again and decide |
| 413 | payload_too_large | 118 | body larger than 256 KB | split into smaller requests |
| 415 | unsupported_media_type | 116 | body that is not application/json | send JSON |
| 422 | validation_error | 113 | invalid parameter or field, unknown field or invalid reference | see details |
| 422 | idempotency_key_reused | 114 | same Idempotency-Key with another body or route | use a new key for each operation |
| 429 | rate_limited | 106 | per-minute limit | wait for Retry-After |
| 429 | quota_exceeded | 107 | monthly quota used up | wait for the reset or ask for more quota |
| 500 | internal_error | — | unexpected Validades error | retry later; if it persists, contact support |
The store_restricted code (109) is reserved for keys restricted to a store, which do not exist yet.
Validation errors
In validation_error, details lists each problem:
| Detail field | Description |
|---|---|
field | the field or parameter with the problem (for example exp_date, limit) |
issue | the problem, in English |
code | type of problem (for example invalid_format, too_big, unrecognized_keys, not_found, inactive) |
Common examples:
- field that does not exist on the resource →
unrecognized_keys; brand_id,category_id,store_idorproduct_idfrom another organization or that does not exist →issue: not_foundon the field;- deactivated store in
store_id→issue: inactive.
Retrying
| Situation | Retry? |
|---|---|
429, 409 idempotency_in_progress | yes, after Retry-After |
500, network failure, timeout | yes, with growing intervals. On POST, use Idempotency-Key to avoid duplicates |
4xx (except the above) | no: fix the request first |