Reference · 01

Errors.

Every status code you'll see, what it means, and how to fix the request.

Error response shape

Every error from the webhook service — 4xx and 5xx alike — returns a JSON body with the same envelope:

Error envelopeJSON

{
  "error": {
    "code": "unauthorized",
    "message": "Authorization header is missing or malformed.",
    "request_id": "req_3f9a1b2c"
  }
}

Field	Description
`code`	Machine-readable error code. Use this in your error-handling logic.
`message`	Human-readable explanation safe to show in logs.
`request_id`	Opaque per-request ID. Include it in support emails so Olbrain can trace the exact request.

Status reference

Status	Meaning	What to do
400	Body couldn't be parsed, or inputs don't match what the agent expects.	Check your JSON shape against the agent's schema in Studio.
400 `runtime_not_applicable`	You hit a run-management endpoint against a conversational agent.	Run-management endpoints are workflow-only.
400 `runtime_not_applicable`	You hit a session-management endpoint against a workflow agent (or vice versa).	Session management endpoints are conversational-only; run management is workflow-only.
404 `session_not_found`	Session doesn't exist, or belongs to a different agent or org.	Confirm the `session_id` and that the key matches the agent that created it.
404 `message_not_found`	Message doesn't exist within the given session.	Confirm both `session_id` and `message_id`.
502 `upstream_timeout`	The agent runtime did not respond in time.	Retry with exponential backoff.
401	Missing or malformed `Authorization` header; key not found, revoked, or expired.	Check the header is exactly `Bearer ak_...`. Verify the key is still active in Studio.
404	Agent doesn't exist, or belongs to a different org than the key. Returned uniformly so we don't leak which.	Verify the `agent_id` in the URL and that the key was minted in that agent's organization.
404 `run_not_found`	The run id doesn't exist, or it doesn't belong to the agent in the URL.	Confirm both ids. Runs are scoped to the agent that started them.
409 `invalid_state_transition`	You called `pause` on a queued run, `resume` on a running run, etc.	Re-fetch the run to see its current state before retrying the action.
413	Request body exceeded 1 MiB on the trigger endpoint.	Upload large payloads via the upload endpoint and reference the `fi_*` id from your JSON.
415	Upload endpoint received a non-multipart request.	Set `Content-Type: multipart/form-data` and send one part named `file`.
422	Validation error on the inputs as defined by the agent.	Check the agent's input schema in Studio.
500	Unexpected server error.	Safe to retry once. If it persists, escalate.
502	Upstream failure or timeout.	Retry with exponential backoff.

Retrying

Retry on 502, 503, and 504 with exponential backoff — start at 1 s, double up to a 60 s cap, give up after roughly 10 minutes. Do not retry on 4xx — they indicate a problem with your request that retrying will not fix.

Idempotency

If a retry could produce a duplicate side effect, include an Idempotency-Key field inside your JSON body. Your agent or workflow can dedupe against it.

Debugging a failed request

Capture the response status and body before doing anything else.
If 401 — confirm the key is still active in Studio and copy it again. Keys are case-sensitive.
If 404 — confirm the agent_id in your URL matches what Studio shows, and that the key was minted from that agent's organization.
If 502 — retry once after 1 s, then escalate.
For sustained issues, email support@olbrain.com with the request id from your client logs and the time of failure.