Errors - SegmentFlow.ai

Envelope

Every error response uses the same shape:

{
  "errorCode": "VALIDATION_ERROR",
  "message": "Human-readable description.",
  "details": { "...": "optional, error-specific" }
}

The errorCode is stable across releases. Switch on it programmatically. The message is meant for humans and may change.

Status codes

Code	Meaning
`200`	Success
`202`	Accepted — work started asynchronously, such as Brand Kit extraction or email processing
`204`	Success, no content
`400`	Bad request — payload validation failed
`401`	Missing or invalid `x-api-key`
`403`	Key valid but lacks the required scope
`404`	Resource not found, or belongs to a different organization
`409`	Conflict — concurrent retry, idempotency lock held, or terminal-state operation
`410`	Gone — a temporary resource or token has expired
`422`	Unprocessable — semantic validation failed (e.g. template incomplete, idempotency key reused)
`429`	Rate limited
`501`	Not implemented

Common error codes

MISSING_CREDENTIAL - no supported credential was supplied (401).
INVALID_API_KEY - x-api-key is invalid or revoked (401).
INSUFFICIENT_SCOPE or API_KEY_SCOPE_INSUFFICIENT - key valid but missing a required scope (403). Includes required field listing the needed scopes.
NOT_FOUND - the resource doesn’t exist or belongs to another organization (404). The API never reveals which.
IDEMPOTENCY_KEY_REUSED - same Idempotency-Key header sent with a different request.
VALIDATION_ERROR - the request is structurally valid but semantically rejected, such as a 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.

​Envelope

​Status codes

​Common error codes

​Cross-organization access

Envelope

Status codes

Common error codes

Cross-organization access