Skip to main content

Documentation Index

Fetch the complete documentation index at: https://segmentflow.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Envelope

Every error response uses the same shape: 
{
  "error": "snake_case_code",
  "message": "Human-readable description.",
  "details": { "...": "optional, error-specific" }
}
The error code is stable across releases — switch on it programmatically. The message is meant for humans and may change.

​
Status codes

CodeMeaning
200Success
202Accepted — work started asynchronously (broadcasts, journey triggers)
204Success, no content
400Bad request — payload validation failed
401Missing or invalid x-api-key
403Key valid but lacks the required scope, or allowSends=false for a send endpoint
404Resource not found, or belongs to a different organization
409Conflict — concurrent retry, idempotency lock held, or terminal-state operation
410Gone — prepared send expired or was already redeemed
422Unprocessable — semantic validation failed (e.g. template incomplete, idempotency key reused)
429Rate limited
501Not implemented (e.g. scheduleAt on broadcast create)

​
Common error codes

  • unauthorized — x-api-key missing or invalid (401).
  • insufficient_scope — key valid but missing a required scope (403). Includes required field listing the needed scopes.
  • send_not_allowed — key lacks the allowSends metadata flag (403).
  • not_found — the resource doesn’t exist or belongs to another organization (404). The API never reveals which.
  • prepared_send_expired — the preparedSendId is past its 15-minute TTL or has already been consumed (410). Call /broadcasts/prepare again.
  • concurrent_redeem — another caller is already redeeming the same preparedSendId (409). Retry; the second call lands on the idempotent replay path.
  • idempotency_key_reuse — same Idempotency-Key header sent with a different body (422).
  • validation_failed — the request is structurally valid but semantically rejected (e.g. template missing a subject or sender profile).

​
Cross-organization access

Reading or writing a resource that belongs to another organization always returns 404 — never 403. This prevents an attacker (or a confused integration) from enumerating which IDs exist in other orgs.