Errors

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'" }
    ]
  }
}

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

Codes#

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 → Billing, which lifts the pause at once. Don't retry until then.

module_disabled#

Reserved for modules a company can turn off. No module can be turned off today, so you won't see it.

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.