Error handling

422 Unprocessable Entity

MARcet validates every DigitalReceipt on ingestion. If validation fails, the API returns 422 with structured details (schema and/or business-rule errors).

Publisher requirements:

Do not retry blindly. Inspect the validation details, correct the payload, and then re-submit.
Keep the same receipt identifier if the business transaction is unchanged; use a new identifier only if the business transaction changed.
Log and surface 422 events (include correlation/receipt IDs and validation codes) so operators can act.
Pre-validate locally (XSD/schema plus basic business rules) to reduce 422 rates.

Transient errors (429/5xx)

Retry with exponential backoff and jitter; honour Retry-After when present.
Cap retries and alert on exhaustion.
Keep POSTs idempotent so repeated attempts are safe.

What to log on 422

Include: timestamp, environment, receipt/transaction identifier, HTTP status 422, validation codes/messages, and a short classification (e.g., schema vs business rule). This enables fast triage and trend analysis.

Idempotency (required)

Use a stable, unique identifier per posted receipt so the server can treat repeated POSTs as the same request.

Guidelines:

The same identifier must not be reused for different business transactions.
Store server responses keyed by this identifier so your publisher can safely resume after failures.
Include the identifier consistently in logs, error reports and callbacks (if used).

Queueing & flow control

Publishers must implement basic queueing to survive temporary outages, rate limits and backpressure without data loss.

Minimum recommendations:

Outbound queue. Buffer receipts until the API acknowledges acceptance.
Durability. Queue state survives restarts and network outages.
Concurrency limits. Throttle workers to a safe level; increase gradually while monitoring 422/429/5xx.
Dead-letter queue (DLQ). Route permanently failing items (e.g., repeated 422 after correction attempts) for manual review.
At-least-once delivery + idempotency. Combined, this yields effectively once-only processing.
Observability. Track queue depth, age of oldest item, retry counts and error rates.
Persist the queue on disk or another durable store so restarts and outages do not lose data.

Retry policy checklist

Use exponential backoff with jitter; honour Retry-After; limit total attempts; reset backoff after a successful call; distinguish 422 (fix-and-retry after correction) from 429/5xx (automatic retry).

Local validation (before POST)

Reduce round-trips and 422 responses by validating before you post:

Schema validation. Validate against ARTS Digital Receipt (and any MARcet extensions you use).
Basic business rules. Totals/VAT consistency; required elements (e.g., BusinessUnit/UnitID); required attributes present.
Signature exclusion. When computing/verifying signatures locally, exclude the Signature element per your verifier procedure.

Operational practices

Environments. Use sandbox to validate end-to-end flows before requesting production access.
Separation. Use separate credentials and endpoints for sandbox vs production.
Monitoring. Alert on spikes in 422/429/5xx, increasing queue depth and long-lived items.
Runbooks. Document standard fixes for common validation errors and transient failures.
Capacity. Increase concurrency gradually and observe impact on validation and error rates.