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#
| HTTP | code | What to do |
|---|---|---|
| 400 | bad_request | Inbound envelope is not valid JSON or misses id, type, source, data. |
| 401 | unauthenticated | Bearer token unknown or revoked. Rotate or create a key. |
| 401 | bad_key | Inbound: X-JaKun-Key unknown, revoked or of another tenant. |
| 401 | bad_signature / stale_signature | Wrong secret or bytes changed after signing / clock more than 300 s off. |
| 403 | service_scope | Integration keys can't call this endpoint. |
| 403 | integrations_admin_only | Needs an owner or admin (Configure integrations). |
| 403 | owner_only | Only the tenant owner (for example, export). |
| 403 | source_not_allowed, no_role | Add the source to the key, or give the key a role. |
| 403 | forbidden | The role doesn't allow this record, field or action. |
| 404 | not_found | No such object, record, key, webhook or event — or not visible to you. |
| 409 | conflict, key_exists, not_retryable, no_handler, no_key, key_revoked | The state doesn't allow it; the message says why. |
| 413 | too_large | Inbound body over 256 KB. |
| 422 | validation_failed | Body or parameters don't fit the schema or the metadata; details lists the fields. |
| 422 | unsafe_url, bad_event, bad_source, bad_role, bad_name | Fix the value named in the message. |
| 422 | handler_failed | Inbound handler raised; see the journal. Resend with the same id after the fix. |
| 429 | rate_limited | Wait Retry-After seconds (details.retry_after on REST/MCP). |
| 5xx | internal_error | Ours. 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.