Core concepts
Errors and request IDs
Handle stable FluxDigest error types and preserve diagnostic request IDs.
Unsuccessful API responses contain a stable error type and code:
{
"error": {
"type": "validation_error",
"code": "subscriber_email_invalid",
"message": "The subscriber email address is invalid.",
"param": "email",
"details": null,
"request_id": "req_01JEXAMPLE"
}
}| Status | Meaning | Retry? |
|---|---|---|
400 | Malformed request | No |
401 | Missing, expired, or revoked credential | No |
403 | Credential lacks the required scope | No |
404 | Resource is absent from the workspace | No |
409 | State or idempotency conflict | Only when marked retryable |
422 | Field validation failed | No |
429 | Rate limit reached | After Retry-After |
500 | FluxDigest API failure | Yes, with backoff |
503 | Temporarily unavailable | Yes, with backoff |
Every response includes X-Request-Id. Preserve it in logs. Share the request
ID, timestamp, and endpoint with support, but never share the API key.
The SDK converts API and transport failures into typed FluxDigestError
subclasses while retaining the original status, code, request ID, and safe
response headers.