Concepts
Errors
On this page
Every error has the same shape: an HTTP status and a JSON body with an error object.
{
"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'" }
]
}
}| Field | Always | What it is |
|---|---|---|
code | Yes | A stable machine code from the table below. Branch on this. |
message | Yes | What went wrong, for a person. It may change wording; don't parse it. |
hint | Often | What to do about it: which field to fix, which action to use instead, or "do not retry". |
details | Sometimes | Structured 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#
| Code | Status | Meaning |
|---|---|---|
bad_request | 400 | The request itself is malformed: an invalid Idempotency-Key, an unknown audience header, a body that isn't JSON. |
validation_failed | 422 | The input doesn't match the action's schema. details lists every problem. |
unauthenticated | 401 | No key, or a key that is malformed, revoked or unknown. |
forbidden | 403 | Your role may not do this, or a machine may not (what machines can see). |
module_disabled | 403 | The module (Time off, Time clock, Documents or Equipment) is turned off for the company. |
ai_disabled | 403 | The company turned AI assistants off for this side (Bizisy or My workspace). |
api_disabled | 403 | The company turned API keys off for this side (Bizisy or My workspace). |
not_allowed | 403 | Bizisy hasn't made this feature available for the company yet (today: Ask HR). |
not_found | 404 | No such action for this key (unknown, or not on the key's audience), or no such record in your company. |
conflict | 409 | The 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_large | 413 | The body is over 2 MiB (photo and logo uploads: 3 MiB). |
unsupported_media_type | 415 | The body isn't application/json. |
rate_limited | 429 | Over the rate limit. Wait Retry-After seconds. |
internal | 500 | Our 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.