Platform guarantees
OpenFiskal publishes these current platform targets for the fiscalization API:| Area | Guidance |
|---|---|
| Availability target | 99.9% monthly for production |
| Typical synchronous latency | p50 < 300 ms, p95 < 1200 ms for standard operation mutations |
| Client timeout guidance | 10s request timeout, 30s total retry budget for synchronous calls |
| Rate limiting | 500 requests/second per API key |
429 behavior | Returns Retry-After in seconds and a stable rate_limit_exceeded error code |
Idempotency and concurrency per endpoint
The table below shows which endpoints requireIdempotency-Key and If-Match (ETag). Endpoints not listed here (all GET, DELETE, and POST /registers/{id}/fiscalize) require neither header.
| Endpoint | Idempotency-Key | If-Match (ETag) |
|---|---|---|
POST /operations | Required | Not used |
POST /operations/{id}/complete | Required | Required |
POST /operations/{id}/void | Required | Required |
PATCH /merchants/{id} | Not used | Not used |
PATCH /registers/{id} | Not used | Not used |
PATCH /locations/{id} | Not used | Not used |
PATCH endpoints for merchants, registers, and locations do not require If-Match or Idempotency-Key. These endpoints apply a last-writer-wins strategy — concurrency control is not enforced on resource metadata updates.
Idempotency rules
SendIdempotency-Key on every mutating operation request (POST /operations, POST /operations/{id}/complete, POST /operations/{id}/void).
The following are Forward-looking platform rules. Clients should code against them, but server-side enforcement is not yet live (see Reserved codes):
- retention window is at least 24 hours
- uniqueness scope is endpoint plus merchant plus authenticated tenant
- reusing a key with the same payload will return the original response
- reusing a key with a different payload will return
409 idempotency_key_conflict
Concurrency rules
Operation mutation endpoints (POST /operations/{id}/complete, POST /operations/{id}/void) require If-Match with the latest operation ETag. Omit it and the API returns 428 precondition_required. Send a stale value and the API returns 412 precondition_failed; the expected and current versions are included in message (e.g. "Resource version mismatch. Expected 1, current is 2."). The If-Match header value must be a quoted positive integer (e.g. "1"); a malformed value returns 400 invalid_request.
PATCH endpoints on merchants, registers, and locations accept updates without If-Match. These are metadata-only mutations where last-writer-wins is acceptable.
Request tracing
Every response includes anX-Request-Id header (e.g. req_a1b2c3d4e5f60718293a). Persist it in your logs and attach it to support cases.