Skip to content

Concepts

Errors

On this page

Every error has the same shape: an HTTP status and a JSON body with an error object.

JSON
{
  "error": {
    "code": "validation_failed",
    "message": "Input is invalid",
    "hint": "Unknown field(s): titel. Accepted fields: given_name, family_name, work_email, title, start_date, …",
    "details": [
      { "code": "unrecognized_keys", "keys": ["titel"], "path": [], "message": "Unrecognized key(s) in object: 'titel'" }
    ]
  }
}
FieldAlwaysWhat it is
codeYesA stable machine code from the table below. Branch on this.
messageYesWhat went wrong, for a person. It may change wording; don't parse it.
hintOftenWhat to do about it: which field to fix, which action to use instead, or "do not retry".
detailsSometimesStructured detail. For validation_failed, the list of problems, each with a path such as ["people", 3, "manager_email"].

Every response, error or not, carries an X-Request-Id header.

Codes#

CodeStatusMeaning
bad_request400The request itself is malformed: an invalid Idempotency-Key, an unknown audience header, a body that isn't JSON.
validation_failed422The input doesn't match the action's schema. details lists every problem.
unauthenticated401No key, or a key that is malformed, revoked or unknown.
forbidden403Your role may not do this, or a machine may not (what machines can see).
module_disabled403The module (Time off, Time clock, Documents or Equipment) is turned off for the company.
ai_disabled403The company turned AI assistants off for this side (Bizisy or My workspace).
api_disabled403The company turned API keys off for this side (Bizisy or My workspace).
not_allowed403Bizisy hasn't made this feature available for the company yet (today: Ask HR).
not_found404No such action for this key (unknown, or not on the key's audience), or no such record in your company.
conflict409The change conflicts with the data as it is (a duplicate email, a reporting cycle, a person not employed that day), or an Idempotency-Key conflict.
payload_too_large413The body is over 2 MiB (photo and logo uploads: 3 MiB).
unsupported_media_type415The body isn't application/json.
rate_limited429Over the rate limit. Wait Retry-After seconds.
internal500Our fault. Retry with the same Idempotency-Key, and quote the X-Request-Id if it persists.

bad_request#

Fix the request; retrying it unchanged fails the same way.

validation_failed#

Inputs are strict: an unknown field is an error, not ignored, and the hint lists the fields the action accepts (so a typo shows up at once). Bulk actions such as org.setup.apply validate everything first and list every problem; nothing is written.

unauthenticated#

Check the Authorization: Bearer hrk_… header. API keys explains why a key stops working.

forbidden#

The message names what isn't allowed and the hint says who can do it. Don't retry: permission errors are final for this key.

A company whose account is paused because an invoice is unpaid past its due day (or its billing details are missing past their deadline) refuses every API key and connected AI app with forbidden and details.reason: "org_paused": "This company's account is paused until an invoice is paid. Your admins have been told." Nothing was deleted and the key is not revoked: an owner or admin pays in Settings → Plan & billing, which lifts the pause at once. Don't retry until then.

module_disabled#

A company can switch Time off, the Time clock, Documents and Equipment off in Settings → Features. Their actions then answer module_disabled, and their tools disappear from MCP. The data is kept: when an owner or admin switches the module back on, everything is there again. Don't retry; tell the user an owner or admin can switch it on. platform.whoami says what is on (features.modules, and time_off, time_clock, documents, equipment).

ai_disabled#

A company can switch AI assistants off in Settings → Features, separately for Bizisy (HR, managers and admins) and for My workspace. A connected AI app on a side that is off gets ai_disabled (403, never 401: the connection is kept, not revoked) with details.kind: "ai" and details.side, and so does an API key used over MCP on that side (an AI app with a key is still an AI assistant; the key keeps working on REST). It works again as soon as an owner or admin switches it back on. Don't retry or reconnect; tell the user.

api_disabled#

The same for API keys: a key on a side the company switched off gets api_disabled (403) with details.kind: "api" and details.side, on REST and MCP alike, and no new key can be created for that side. The key is kept and works again when the side is switched back on. Installed marketplace apps and webhooks are not affected by either switch.

not_allowed#

Some features are switched on for a company by Bizisy before the company can use them; today that is Ask HR and its AI features. Until then, and if Bizisy later withdraws it, its actions answer not_allowed (403). The company's data is kept. Don't retry; tell the user that an owner or admin can ask Bizisy for it in Settings → Ask HR.

not_found#

For an action: check its id and that your key's audience serves it (a Me key can't call Manage actions). For a record: the id doesn't exist in your company, or you may not see it.

conflict#

Read the current state, then decide. The hint usually says what to do instead (for example "use org_people_correct_job"). "The organization is busy right now" is a conflict you can retry after a moment.

payload_too_large#

Split the work: bulk imports take at most 250 people per call.

unsupported_media_type#

Send Content-Type: application/json.

rate_limited#

Wait the number of seconds in Retry-After, then retry.

internal#

Something failed on our side and nothing was saved, unless the message says the outcome is unknown. Retry with the same Idempotency-Key. If it keeps failing, write to hello@bizisy.com with the X-Request-Id.

Through MCP#

Tool errors carry the same code, message and hint in the tool result (isError: true), plus a view_url to the Activity entry of the failed attempt, so an assistant can read the hint and tell the person what to do.

Retrying#

Errors worth retrying say when: retry_after_seconds in the error (and a Retry-After header on the REST API). A busy organization (409 conflict, "The organization is busy right now"), an Idempotency-Key still running and the rate limit carry it. Wait that long and retry the same request, at most three times; then stop and say so. Errors without it (forbidden, validation_failed, not_found, other conflicts) won't succeed by retrying: fix the request.

Something missing or wrong on this page? Write to hello@bizisy.com.

Developer docs