Error envelope

Synchronous request errors use a flat JSON envelope. The error field is the stable machine-readable value to switch on. Some responses can include detail, message, or retry_after_seconds when extra context is available.

Error response

{
  "error": "invalid_run_mode"
}

HTTP status map

Status	Meaning	Client action
400	Missing or invalid request parameters.	Fix the request before retrying.
401	Missing, invalid, expired, or unavailable API key.	Refresh or replace the key. Do not retry blindly.
403	The authenticated principal lacks permission.	Check workspace role, team access, or endpoint permission.
404	The resource does not exist or is not visible.	Check IDs and workspace scope.
409	The request conflicts with current state.	Resolve the conflict before retrying. For run creation, inspect Idempotency-Key usage.
422	JSON is valid but field values cannot be processed.	Fix field values or selected Kit inputs.
429	Rate limit exceeded.	Wait for Retry-After or retry_after_seconds before retrying.
500	Unexpected Semarize-side error.	Retry with backoff if the operation is idempotent; escalate if persistent.

Common error codes

Code	Typical cause
missing_bearer_token	Authorization header was omitted or malformed.
invalid_api_key	API key is not valid for the requested workspace context.
api_key_expired	API key has an expiration date in the past.
kit_code_or_kit_version_id_required	Run or test request did not identify a Kit.
input_must_be_object	The input field was not a JSON object.
invalid_run_type	The type field is not an accepted run type.
invalid_run_mode	The mode field is not async or sync.
kit_not_found	The selected Kit is missing or not visible to the workspace.
idempotency_key_conflict	The same Idempotency-Key was reused for a conflicting request.
run_request_failed	The run request could not be accepted or processed.

Terminal run failures

A POST /v1/runs request can succeed while the run later fails. In that case the HTTP request is not the failure boundary; the run status is. Poll or receive the terminal webhook, then inspect error_code, error_message, and error_user_message when present.

Failed run detail

{
  "run_id": "run_uuid",
  "status": "failed",
  "error_code": "run_request_failed",
  "error_message": "Internal diagnostic message when available",
  "error_user_message": "Safe user-facing message when available"
}

Logging

Log HTTP status, error, retry_after_seconds, run_id, and request id when available.
Log the Kit identifier and upstream source record id, but avoid logging raw conversation content unless your data policy allows it.
Preserve the Idempotency-Key for run creation failures so support can reason about duplicate-prevention behavior.

Related guides

Async runs

Create runs, poll safely, handle sync fallback, and use webhooks for terminal events.

Idempotency

Use Idempotency-Key so retrying run creation does not create duplicate work.

Rate limits

Respect Retry-After, slow polling loops, and build controlled batch workers.

Versioning

Understand /v1 stability, additive changes, and Kit version pinning.

Status

Use status signals, incident retry behavior, and escalation details in production.

Errors