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.