Retries And Status

Every write requires an Idempotency-Key: 8 to 128 characters using letters, digits, ., _, : or -. Keep it stable for the same logical request, including after timeouts.

Replaying the same key and normalized JSON returns the existing record. Changed content returns 409 IDEMPOTENCY_CONFLICT. A different key with an existing external reference returns 409 EXTERNAL_REFERENCE_EXISTS. Keys are scoped to the tenant, environment and resource type, not to the individual credential, so rotating credentials does not lose deduplication.

Lifecycle

Status	Meaning	Next action
PENDING	Stored, submitting or awaiting reconciliation	Poll the returned ID
COMPLETED	Fiscal evidence or stock outcome verified	Retain result; fiscal PDFs are available
REGISTERED	Product registration confirmed	Product can be invoiced
SIMULATED	Sandbox simulation only	Do not treat as KRA acceptance
ACTION_REQUIRED	Configuration, evidence or delivery needs review	Retain ID; contact account administrator or support

Bizflow attempts fiscal delivery promptly and retains a durable recovery record. Uncertain delivery is not blindly repeated. A service restart or caller timeout does not justify a new invoice identity. Some uncertain outcomes require manual reconciliation.

Poll after roughly 5 seconds, then back off to 15-30 seconds. There are no customer webhooks in v1. List your API records with GET /documents?page=0&size=20.

Errors

Errors have a stable Bizflow envelope:

{"error":{"code":"IDEMPOTENCY_CONFLICT"}}

400 INVALID_REQUEST means malformed or unsupported fields. 409 reports state conflicts. 422 FISCAL_VALIDATION_FAILED means the account or fiscal data needs correction. 503 means temporarily unavailable. Never infer fiscal rejection from a transport error: retry the same idempotency key or retrieve the known record ID first.