Semogram Docs
APIUsing the API

Errors and limits

Handle validation, authorization, capacity and uncertain writes

The API uses HTTP status to distinguish success from failure. Newer routes return an error object; older routes may return an error string or a validation object. Support both shapes.

{"ok":false,"error":{"code":"actor_required","message":"This API key must be linked to an organization administrator for pipeline authoring or execution.","details":null}}
StatusResponse to take
400Correct the body, filters or snapshot/version selector
401Check the Bearer credential, expiry and revocation
402Inspect workspace plan/usage limits; repeating the request cannot increase allowance
403Check scope, resource boundary, actor, named grants and policies
404Check workspace and resource IDs; some inaccessible resources appear unavailable
409Inspect revision, idempotency conflict, references or active work before retrying
410An expiring result is no longer usable; start a new authorized query if needed
429Honor Retry-After and back off
5xxPreserve the request identity; determine whether work was accepted before retrying writes

An unexpected server failure returns a generic message and a reference, never internal database or provider details. Quote the reference when you contact support:

{"error":"Something went wrong. Try again, or contact support with the reference.","reference":"6f1c2c1e-3b1a-4b8e-9a52-0f7e2d6c9a11"}

Request limits include workspace and credential windows. Read returned rate-limit headers when present. A capacity rejection can return 503 with Retry-After; a request-rate rejection and a plan quota are separate limits. Starting a pipeline run returns the same answers as the app: 402 with code: "usage_limit_reached" when the plan's included usage is used up, and 503 with Retry-After when execution capacity is full.

For a failed pipeline dispatch response, retry with its original idempotency key or inspect the known run. For a source write, inspect its operation record and use the recovery action when appropriate. A network timeout is not evidence that no data changed.

Log method, resource IDs, status and safe error fields. Avoid recording API keys, connector passwords or full sensitive records. Workspace activity helps correlate query and operation history.