Skip to main content

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" }
]
}
}
FieldDescription
codestable error code. Use this field in your code.
internal_codeerror number, useful when talking to support
messagedescription in English, for people. It may change: do not base decisions on it
request_idrequest identifier. It also comes in the X-Request-Id header of every response
detailswhen 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​

HTTPcodeInternalWhen it happensWhat to do
400invalid_json117the body is not valid JSONfix the JSON
401invalid_api_key101missing, invalid, revoked or expired key, or key sent in the URLcheck the key and the header
402subscription_inactive105the organization has no active subscriptionrenew the subscription
403api_access_not_enabled102the API is not enabled for the organizationrequest access in the panel
403api_access_suspended103access was suspendedcontact support
403workspace_not_eligible104the key belongs to a personal workspaceuse an organization
403insufficient_scope108the key lacks the required scope (details.required_scope)use a key with the right scope
403terms_not_accepted130the deadline to accept the new version of the terms has passedthe owner or an admin accepts the terms in the panel
404not_found110route, item or id does not exist, or the item belongs to another organizationcheck the id
406not_acceptable115Accept asks for a format other than JSON or XMLuse JSON or XML
409conflict128the id sent in a POST already existsuse another id or fetch the item
409store_has_products111deleting a store with products without cascade=true (details has the counts)see Stores
409idempotency_in_progress129the same Idempotency-Key is still being processedwait for Retry-After and retry
412precondition_failed112If-Match does not match the current version (the current ETag comes in the response)read the item again and decide
413payload_too_large118body larger than 256 KBsplit into smaller requests
415unsupported_media_type116body that is not application/jsonsend JSON
422validation_error113invalid parameter or field, unknown field or invalid referencesee details
422idempotency_key_reused114same Idempotency-Key with another body or routeuse a new key for each operation
429rate_limited106per-minute limitwait for Retry-After
429quota_exceeded107monthly quota used upwait for the reset or ask for more quota
500internal_error—unexpected Validades errorretry 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 fieldDescription
fieldthe field or parameter with the problem (for example exp_date, limit)
issuethe problem, in English
codetype 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_id or product_id from another organization or that does not exist → issue: not_found on the field;
  • deactivated store in store_id → issue: inactive.

Retrying​

SituationRetry?
429, 409 idempotency_in_progressyes, after Retry-After
500, network failure, timeoutyes, with growing intervals. On POST, use Idempotency-Key to avoid duplicates
4xx (except the above)no: fix the request first