Status page
Use https://status.semarize.com as the human-readable status page for Semarize availability and incident updates. Your own integration should still rely on API responses, retries, and durable state rather than a manual status check alone.
Incident behavior
| Signal | Client behavior |
|---|---|
| 5xx from POST /v1/runs | Retry with backoff and the same Idempotency-Key for the same logical request. |
| 429 | Wait for Retry-After or retry_after_seconds before retrying. |
| Long queued/running state | Continue bounded polling or wait for webhook delivery. Avoid tight loops. |
| Webhook delivery delay | Poll GET /v1/runs/{runId} for critical workflows and dedupe any later webhook event. |
Durable integration state
Keep enough local state to resume after an incident, worker restart, or delayed webhook. The goal is to know whether a source record already has a Semarize run and what the next safe action is.
- Store source record id, Kit identifier, Idempotency-Key, Semarize run_id, status, and next_poll_at.
- Keep terminal status, error_code, and error_message for replay decisions.
- Separate create-run retries from poll retries so you do not create duplicate runs.
Support context
When escalating a production issue, include the minimum data needed to trace the request without exposing unnecessary conversation content.
| Include | Why |
|---|---|
| run_id | Primary identifier for accepted runs. |
| Idempotency-Key | Useful for duplicate-prevention and retry analysis. |
| Timestamp and endpoint | Narrows logs and status windows. |
| HTTP status and error code | Separates request validation, authorization, limits, and runtime failures. |
| Workspace or account context | Confirms which tenant and key scope were involved. |
Safe replay
Replay only from durable source records. Before creating a new run, check whether the source record already has a Semarize run_id. If it does, poll the existing run or decide explicitly to create a new run with a new Idempotency-Key.
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.
Errors
Map HTTP status codes, flat error envelopes, and terminal run failure fields.
Rate limits
Respect Retry-After, slow polling loops, and build controlled batch workers.
Versioning
Understand /v1 stability, additive changes, and Kit version pinning.