BizKitHub
DocsError Codes

Error Codes Reference

Complete reference of all internal error codes generated by the BizKitHub core application. These codes appear in system logs, API responses, and admin notifications.

Error Database
Total Codes67
FormatJSON Response
Categories4 types
Error Response Format

All API errors follow a consistent JSON format with error code, message, and description fields.

View API Reference
Showing 67 of 67 error codes
500
INTERNAL_ACCOUNT_CAN_NOT_DETERMINATE_USER_IP

Can not determinate user IP.

Failed to detect user IP address from HTTP request.

Internal1 steps
429
INTERNAL_TOO_MANY_REQUESTS

Rate limit exceeded

You have exceeded the rate limit for requests. Please try again later.

Internal2 steps
401
INTERNAL_USER_MUST_BE_AUTHORIZED

User must be authorized

User is not logged in.

Internal1 steps
410
INTERNAL_ACCOUNT_HAS_BEEN_DELETED

Account has been deleted and cannot be used or re-registered.

The contact behind this account is soft-deleted (shop__contact.deleted_date IS NOT NULL). Soft-deleted contacts hold the email slot until the record is anonymised, so re-registration under the same email is blocked and any lingering session is invalidated. This is intentional so the address history stays auditable.

Internal2 steps
403
INTERNAL_EMAIL_NOT_VERIFIED

Please verify your e-mail before signing in.

The account exists as a pending shop__contact_register_request row that has not yet been confirmed. The caller must either enter the 6-digit code from the confirmation e-mail or click the link in it. The register row survives for 24 hours after signup; expired rows are treated as if the account never existed.

Internal3 steps
423
ORGANISATION_IS_SUSPENDED

The organisation is suspended.

The organisation has been suspended (frozen) by the platform operator, typically because its tariff expired or its owner requested account closure. Its data is kept intact, but API access, background processing and new file uploads are stopped until the organisation is resumed.

General2 steps
401
INTERNAL_ORGANISATION_IS_REQUIRED

Organisation context is required

Provide a valid organization ID or slug.

Internal1 steps
404
INTERNAL_RESOURCE_NOT_FOUND

Resource not found.

A specific resource referenced by the request (a record id, slug, hash or token) does not exist in the organisation scope, has been deleted, or the caller has no permission to see it. Attach the missing identifier as parametric context — e.g. `throw ApiError("INTERNAL_RESOURCE_NOT_FOUND", "Calendar 42")`.

Internal3 steps
415
INTERNAL_LOGO_UNSUPPORTED_TYPE

The logo must be a PNG, JPG, WebP or SVG image.

The uploaded file is not an image, or it is an SVG that could not be rendered. SVG logos are converted to PNG because most e-mail clients do not display SVG.

Internal1 steps
400
INTERNAL_VALIDATION_FAILED

Request payload failed validation.

The server-side validator rejected a field value that the typed body schema could not catch (format, length, cross-field consistency, multi-tenant ownership, etc.). The offending field and constraint should be passed as parametric context — e.g. `throw ApiError("INTERNAL_VALIDATION_FAILED", 'reserveFrom must be a relative-time string')`.

Internal3 steps
500
INTERNAL_ORDER_INSERT_FAILED

Inserting order failed

An error occurred while inserting the order into the database. Failed to create order after multiple attempts

Internal2 steps
503
INTERNAL_COMGATE_PRODUCTION_NOT_ENABLED

Comgate merchant is configured for production but only test mode is enabled on the gateway side.

BizKitHub holds the Comgate gateway instance with environment="p" (production), but a pre-flight probe against the Comgate API returned error code 1308 ("Production environment is not enabled for you, it is enabled testing environment only"). Forwarding a customer to the gateway in this state would produce a broken payment page for every order. The platform refuses to create the payment until the misconfiguration is fixed.

Internal3 steps
404
INTERNAL_ORGANISATION_NOT_FOUND_OR_USER_NOT_MEMBER

Organisation not found or user is not a member.

The specified organisation does not exist, or the user is not a member of the organisation.

Internal3 steps
502
INTERNAL_FIO_API_UNAVAILABLE

Fio API is temporarily unavailable.

The upstream Fio bank API did not return a parseable response within the timeout window. The most common causes are scheduled Fio maintenance, a token that was just rotated, or a brief network glitch between Vercel and Fio. The raw response body is appended to the error message for debugging.

Internal3 steps
429
INTERNAL_AI_RATE_LIMITED

AI request rate limit exceeded.

Each organisation member may start a limited number of AI requests (Assistant, chat, translation, content generation, newsroom) per 10 minutes and per day. The limit protects the organisation from runaway scripts and unexpected AI spend.

Internal2 steps
429
INTERNAL_AI_BUDGET_EXCEEDED

Monthly AI token budget of your tariff has been used up.

The organisation has consumed all AI tokens included in its tariff for the current calendar month (`limit_ai_tokens_monthly`). AI features using the shared BizKitHub key are paused until the next month.

Internal3 steps
429
INTERNAL_FIO_RATE_LIMITED

Fio API rate limit hit (one call per token every 30 s).

Fio answered HTTP 409 because the same API token was already used within the last 30 seconds. Fio enforces this per token, across every client, so an earlier call from another system (or an aborted call of ours) also counts.

Internal2 steps
502
INTERNAL_FIO_STATEMENT_INVALID

Fio bank statement is malformed.

A statement file received from Fio (GPC or transaction JSON) is missing required fields or breaks the expected structure (no 074 header, empty payload, unparseable transaction line). The offending row or snippet is appended to the error message.

Internal3 steps
502
INTERNAL_FIO_TOKEN_INACTIVE

Fio API token is inactive.

Fio refused the request with `<status>error</status>`. This almost always means the API token stored in `shop__bank` for this account has been revoked, expired, or never activated. Fio tokens must be activated manually in Fio internet banking and have a fixed validity window.

Internal2 steps
401
PERMISSION_MEMBER_IS_BLOCKED_IN_ORGANISATION

Organisation member has been blocked.

Your user account within the organisation has been blocked. For further information, please contact your organisation administrator.

Permission3 steps
403
PERMISSION_MEMBER_HAS_NO_PERMISSION

Member has no permission.

The authenticated member is part of the organisation but their role does not grant access to the requested module or action. Attach the module/action as parametric context when throwing — e.g. `throw ApiError("PERMISSION_MEMBER_HAS_NO_PERMISSION", "calendar:update")`.

Permission2 steps
404
PUBLIC_API_KEY_DOES_NOT_EXIST

Organisation API key does not exist or is broken.

Parameter "apiKey" is always required.

Public API
404
PUBLIC_API_KEY_SAMPLE_VALUE

Sample API key cannot be used.

You are using a sample API key intended only for documentation and testing examples. Please replace it with a real API key generated in your organisation settings.

Public API
400
PUBLIC_API_KEY_IS_NOT_IN_VALID_FORMAT

Organisation API key does not match expected format.

Please use 32 char length key generated from system.

Public API
404
PUBLIC_API_KEY_HAS_BEEN_DELETED

Organisation API key has been deleted.

Public API
403
PUBLIC_API_KEY_IS_NOT_ACTIVE

Organisation API key is not active now.

Public API
401
PUBLIC_API_KEY_IS_EMPTY

Organisation API key is empty. Please add your API key to request query.

Public API
403
PUBLIC_API_KEY_HAS_BEEN_EXPIRED

Organisation API key has been expired.

Public API
401
PUBLIC_IDENTITY_IS_EMPTY

Contact identity is missing. Pass the `identityId` returned by `/customer/login`.

Public API
401
PUBLIC_IDENTITY_IS_INVALID

Contact identity is not valid (unknown, deleted, unauthorized or expired). Log the customer in again.

The `identityId` does not resolve to an active login session of a contact in the organisation behind the API key. The same answer is returned for every failure reason so identities cannot be probed.

Public API
403
PUBLIC_API_KEY_SCOPE_NOT_ALLOWED

API key does not have the required scope for this endpoint.

The API key is valid but has scope restrictions that do not include access to this endpoint. Each API key can be limited to specific scopes (e.g. "carddav", "feed.product"). If the key has any scopes assigned, only those endpoints are accessible.

Public API3 steps
429
PUBLIC_API_KEY_TOO_MANY_REQUEST

Too many requests

The API request limit for this API key (or organisation) has been exceeded. Requests are counted in fixed 10-minute time blocks. Each block has a maximum number of allowed requests. Once the limit is reached, the API will temporarily reject further requests until the next 10-minute block begins. This mechanism is enforced to protect platform stability and to guarantee overall service reliability and SLA for all customers in a multi-tenant environment.

Public API5 steps
400
PUBLIC_CRON_JOB_CODE_INVALID

Cron job code is empty or invalid.

The `code` sent to `/cron-run/start` contains no usable characters after normalization. Codes keep letters, digits and `. _ : -`, up to 64 characters.

Public API2 steps
429
PUBLIC_CRON_JOB_LIMIT_EXCEEDED

Too many distinct cron jobs in this organisation.

Every new `code` creates a cron job. The organisation reached the maximum number of distinct jobs, usually because a variable part (an id, a date) was put into the job code.

Public API2 steps
429
PUBLIC_CRON_RUN_LIMIT_EXCEEDED

Too many cron runs are open at the same time.

The organisation holds the maximum number of simultaneously running cron runs. Runs that are never finished stay open until their expiration.

Public API2 steps
404
PUBLIC_CRON_RUN_NOT_FOUND

Cron run does not exist.

No cron run with this id exists in the organisation behind the API key.

Public API1 steps
409
PUBLIC_CRON_RUN_CLOSED

Cron run is already finished.

The run was already finished, so it accepts no more log entries, heartbeats or finish calls.

Public API1 steps
409
PUBLIC_CRON_RUN_EXPIRED

Cron run expired and was closed as timed out.

No call arrived within the run expiration, so the run was closed as `timeout` and a critical log entry was written. Every log or heartbeat call extends the expiration.

Public API2 steps
422
PUBLIC_CRON_RUN_LOG_LIMIT

Cron run reached the maximum number of log entries.

A single run can hold at most 10 000 log entries. Further entries are rejected.

Public API1 steps
422
PUBLIC_CRON_PAYLOAD_TOO_LARGE

Cron payload is too large.

A log batch exceeds 100 entries. Oversized `meta`, `report` and log `context` (over 16 KB of JSON) are not rejected but stored as a truncation marker.

Public API1 steps
429
PUBLIC_CRON_RUN_RATE_LIMITED

Cron monitor request quota of the API key is exhausted.

Requests to `/api/v1/cron-run/*` have their own fixed hourly quota per API key (separate from the quota of other endpoints). Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers.

Public API3 steps
400
PUBLIC_CRON_SCHEDULE_INVALID

Cron schedule is not a valid cron expression or time zone.

`schedule` must be a standard 5-field cron expression (or 6 fields with seconds), e.g. `*/5 * * * *`, and `scheduleTimezone` an IANA time zone, e.g. `Europe/Prague`. In `/cron-run/start` and `/cron-run/record` an invalid schedule does not reject the run: it is ignored and reported in `warnings`.

Public API1 steps
400
PUBLIC_CRON_RUN_RECORD_INVALID

Recorded cron run has invalid timestamps.

`startedAt` and `finishedAt` must be ISO-8601 times, `startedAt` must not be after `finishedAt`, neither may lie more than 5 minutes in the future and `startedAt` may be at most 7 days old.

Public API1 steps
422
PUBLIC_REQUEST_VALIDATION_FAILED

Request does not match the endpoint schema.

The body, query or path parameters failed schema validation. The response lists the offending fields in `errors` (`path` + `message`) and the request part in `on` (`body`, `query`, `params`). The schema of every endpoint is in the Swagger documentation.

Public API2 steps
400
PUBLIC_REQUEST_BODY_PARSE_FAILED

Request body could not be parsed.

The body is not valid JSON (or does not match its `Content-Type`).

Public API1 steps
404
PUBLIC_CALENDAR_DOES_NOT_EXIST

Calendar does not exist.

Calendar does not exist, please check your calendar code and your permission.

Public API
422
ISSUE_EMAIL_HAS_NO_RECIPIENTS

The e-mail has no recipient.

Nobody would receive this issue e-mail (BIZKIT-75): the author is never e-mailed their own reply, and the remaining participants have no e-mail address, muted the issue, or the organisation turned issue e-mails off. Nothing was changed. Add the customer as reporter / watcher, or save the text as an internal comment.

General
409
PUBLIC_CALENDAR_IS_ARCHIVED

Calendar is archived.

The calendar has been archived (BIZKIT-109): it keeps its history but accepts no new events or reservations. Restore it in the admin (Calendars → show archived → Restore) to use it again.

Public API
404
PUBLIC_CALENDAR_EVENT_DOES_NOT_EXIST

Calendar event does not exist.

The event code does not exist in this organisation, or the customer behind `identityId` has no paid reservation of it and is not its attendee. Both cases answer 404 so foreign events are not disclosed.

Public API2 steps
404
PUBLIC_ORDER_DOES_NOT_EXIST

Order does not exist.

The order hash does not match any order of the organisation behind the API key.

Public API
409
PUBLIC_PAYMENT_TRANSACTION_CONFLICT

Store transaction is already recorded on another order.

An in-app purchase transaction id can pay exactly one order. The same id was already recorded on a different order.

Public API1 steps
404
PUBLIC_FORM_DOES_NOT_EXIST

Form does not exist or is not active.

The form referenced by code or slug does not exist in this organisation, or its `active` flag is false and it has been hidden from the public API. Inactive forms intentionally return 404 (not 403) so the existence of internal-only forms is not disclosed.

Public API2 steps
404
PUBLIC_PRODUCT_DOES_NOT_EXIST

Product does not exist.

Product does not exist, please check your slug.

Public API
409
PUBLIC_PRODUCT_OUT_OF_STOCK

Product is out of stock.

The order asks for more pieces than the warehouse has available (stock minus active reservations). Only warehouses that do not allow negative stock are checked. The order was not created.

Public API1 steps
403
REVIEW_NOT_ALLOWED

You cannot write this review yet.

Reviews can only be written by customers with a delivered order (for a product review, an order containing that product), at least a few days after delivery, and only once per order. Call GET /shop/review/allowance first.

General
400
REVIEW_INVALID

The review could not be accepted.

The rating must be 1 to 5, the author name is required and the text must be at most 1000 characters without spam (links, repeated characters).

General
404
REVIEW_DOES_NOT_EXIST

Review does not exist.

No review with this id exists in the organisation.

General
404
PUBLIC_CATEGORY_DOES_NOT_EXIST

Category does not exist.

Category does not exist, please check your slug.

Public API
404
PUBLIC_PAYMENT_DOES_NOT_EXIST

Payment does not exist.

The payment id, gateway id or hash referenced by the request does not match any payment record in the current organisation. Payments are not soft-deleted, so this almost always means the identifier is wrong or refers to a payment in a different organisation.

Public API2 steps
429
PAYMENT_RETRY_LIMIT_EXCEEDED

Vícenásobné pokusy o platbu se nezdařily, kontaktujte podporu.

The customer has tried to initiate an online payment for the same order at least 3 times in the last 10 minutes and every attempt failed before the gateway accepted it (most commonly because the merchant gateway is in a misconfigured state, e.g. Comgate 1308/1400, the merchant account is inactive, or upstream is down). To stop the customer from busy-looping into a dead gateway, the platform short-circuits further attempts until the cool-off window expires — the previous failure log entries identify the actual root cause.

General3 steps
404
PUBLIC_LOCK_DOES_NOT_EXIST

Lock does not exist.

The TTLock referenced by id/code is not registered for this organisation, has been deleted, or your API key has no permission to control it.

Public API2 steps
409
PUBLIC_LOCK_IS_NOT_ACTIVE

Lock is not active.

The lock exists and belongs to this organisation but is currently marked inactive (e.g. offline, deactivated by an admin, or its TTLock pairing was revoked). Inactive locks reject all passcode and unlock operations until reactivated.

Public API2 steps
404
PUBLIC_CUSTOMER_DETAIL_NOT_PERMITTED

You have no permission to load this customer detail.

Wrong cuRefNo or your profile is not manager of this customer.

Public API
400
PUBLIC_CUSTOMER_CAN_NOT_ASSIGNEE_ITSELF

Customer can not assignee itself.

Public API
404
PUBLIC_POST_COMMENT_PARENT_NOT_FOUND

Parent comment does not exist.

A new post comment was submitted with a `parentExternalId` that does not match any existing comment on the same post. The most common cause is that the parent comment was deleted between the time the reply UI was rendered and the time the user pressed submit.

Public API2 steps
400
PUBLIC_TAG_USE_INVALID_FORMAT

Tag use invalid format.

Tag key and value must be non-empty strings with a maximum length of 200 characters each.

Public API
400
PUBLIC_COUNTRY_CODE_UNKNOWN

Unknown country code.

The `country` query parameter must be a valid ISO 3166-1 alpha-2 code (e.g. "CZ", "SK", "DE"). The endpoint uses it to filter posts by geo-availability rules (per-country + per-continent). When omitted, no geo filter is applied — callers that do not need the filter can drop the parameter entirely to preserve the legacy behaviour.

Public API2 steps

HTTP Status Codes

4xx

Client Errors

Request issues
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 429Too Many Requests
5xx

Server Errors

Server issues
  • 500Internal Server Error
  • 502Bad Gateway
  • 503Service Unavailable
  • 504Gateway Timeout
2xx

Success

Successful requests
  • 200OK
  • 201Created
  • 204No Content