Errors

One error envelope for every endpoint, stable machine codes and what to do about each.

Every error has the same shape. Switch on code — it is stable. message is for people and may change or be translated.

HTTP/1.1 403 Forbidden
{"error": {"code": "integrations_admin_only",
           "message": "…",
           "details": null}}

Codes#

HTTPcodeWhat to do
400bad_requestInbound envelope is not valid JSON or misses id, type, source, data.
401unauthenticatedBearer token unknown or revoked. Rotate or create a key.
401bad_keyInbound: X-JaKun-Key unknown, revoked or of another tenant.
401bad_signature / stale_signatureWrong secret or bytes changed after signing / clock more than 300 s off.
403service_scopeIntegration keys can't call this endpoint.
403integrations_admin_onlyNeeds an owner or admin (Configure integrations).
403owner_onlyOnly the tenant owner (for example, export).
403source_not_allowed, no_roleAdd the source to the key, or give the key a role.
403forbiddenThe role doesn't allow this record, field or action.
404not_foundNo such object, record, key, webhook or event — or not visible to you.
409conflict, key_exists, not_retryable, no_handler, no_key, key_revokedThe state doesn't allow it; the message says why.
413too_largeInbound body over 256 KB.
422validation_failedBody or parameters don't fit the schema or the metadata; details lists the fields.
422unsafe_url, bad_event, bad_source, bad_role, bad_nameFix the value named in the message.
422handler_failedInbound handler raised; see the journal. Resend with the same id after the fix.
429rate_limitedWait Retry-After seconds (details.retry_after on REST/MCP).
5xxinternal_errorOurs. Retry with backoff; inbound events with the same id.

MCP returns JSON-RPC errors inside a 200 response ({"jsonrpc":"2.0","error":{"code":-32601,…}}) for protocol problems, and tool errors in the tool result.