Snippet

Error code table

The full taxonomy lives at docs/sdk-standards/error-taxonomy.md in the GetFluxly repo. This is the user-facing summary.

HTTP	`error` code	Retryable	Meaning
400	`validation_error`	No	Request shape is wrong; fix the payload
401	`unauthenticated`	No	API key missing or unknown
403	`forbidden`	No	Valid key, no access to the resource
403	`wrong_key_type`	No	Right key, wrong classification, see key types
404	`not_found`	No	Resource doesn't exist
408	`timeout`	Yes	Server didn't respond in time; retry with same `X-Idempotency-Key`
409	`alias_conflict`	No	Two profiles claim the source ID; pick one and re-alias
409	`erasure_in_progress`	No	A prior erasure is still running
413	`payload_too_large`	No	Body exceeds endpoint limit
425	`too_early`	Yes	Backend warming up; retry shortly
429	`rate_limited`	Yes	Honor `Retry-After`
500–599	`server_error`	Yes	Transient; SDKs retry with backoff

SDK error shape

All SDKs translate these into a typed error with the same fields:

{
  code: "rate_limited",
  retryable: true,
  retryAfterMs: 2000,
  message: "...",
  details: { ... },
}

retryable indicates whether the SDK will retry by default. If you're integrating directly against the REST API, replicate that posture: retry on retryable: true with X-Idempotency-Key preserved.