Skip to content

Public API: authentication, errors and limits

How to send the key, how to read errors and how many requests per minute each key allows.

Address and documentation

Every route starts with /api/v1/public/v1/ on the same address your ERP uses. The full documentation (OpenAPI, with examples) is at /api/v1/public/docs and the file at /api/v1/public/openapi.json. In API and developers you have the API documentation button.

Authentication

Send the key in every request with the header Authorization: Bearer bzk_YOUR_KEY. The store comes from the key: you do not need to give it. Test the key with GET /api/v1/public/v1/me, which returns the store, the key permissions and the limit.

Errors

Errors come as JSON with statusCode, errorCode and message. Always decide on the errorCode (the message is in Spanish and may change):

  • API_KEY_INVALID, API_KEY_REVOKED, API_KEY_EXPIRED (401): the key does not work.
  • API_KEY_IP_NOT_ALLOWED (403): the request comes from an IP that is not in the key list.
  • API_SCOPE_MISSING (403): the key lacks the permission of that route.
  • API_PERMISSION_MISSING (403) or API_KEY_OWNER_UNAVAILABLE (401): the person who created the key no longer has that permission or can no longer access the store.
  • MODULE_SUBSCRIPTION_REQUIRED or MODULE_DISABLED (403): the API service or the module of the resource is not active in the store.
  • API_NOT_FOUND (404): it does not exist in this store.

Rate limit

Each key allows 120 requests per minute. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the minute restarts). Over the limit you get 429 API_RATE_LIMITED with the Retry-After header: wait that many seconds before repeating.

Back to the help centre