Error taxonomy

Every 4xx and 5xx has the same body. code is the stable, machine-readable identifier — branch on it, never on message.

{
  "error": {
    "type": "validation_error",
    "code": "hr.device_missing_isu",
    "message": "Device VM-0043 has no ISU number assigned. Register the premises in ePorezna and add the ISU number before fiscalizing.",
    "param": "device_id",
    "upstream": null,
    "doc_url": "https://docs.fiskhub.com/errors/hr.device_missing_isu"
  }
}

Field	Notes
`type`	The broad category. A closed set — useful for handling a `code` you do not recognise.
`code`	Stable forever. Never renamed, never repurposed. New codes may be added.
`message`	Human-readable and actionable. Not part of the contract — reworded freely.
`param`	The offending request field or header, when there is one.
`upstream`	Raw detail from the Tax Administration, for debugging. Not part of the contract.
`doc_url`	The page for this exact code. Always resolves.

Types

`type`	HTTP	Meaning
`validation_error`	400	The request is wrong. Retrying it unchanged cannot help.
`authentication_error`	401	The key is missing, unknown or revoked.
`authorization_error`	403	The key is valid but not allowed to do this.
`not_found`	404	No such resource is visible to this key.
`conflict`	409	The request conflicts with existing state.
`rate_limit_error`	429	Too many requests. Back off and retry with the same key.
`fiscal_error`	—	Carried inside a `200` invoice body, not as an HTTP error.
`upstream_error`	—	Reported through the invoice’s `fiscal_error`, not as an HTTP error.
`internal_error`	500	Our fault. Retry with the same `Idempotency-Key`.

Handle an unrecognised code by falling back to its type:

switch (error.code) {
  case "hr.device_missing_isu":
    return alertOperator(error);
  case "upstream_unavailable":
    return keepSelling();
  default:
    return error.type === "validation_error" ? alertOperator(error) : retryLater(error);
}

All codes

Request shape

Code	HTTP	Retry?
`invalid_request`	400, 404, 409	No — fix the request
`missing_idempotency_key`	400	No — add the header
`idempotency_key_reused`	409	No — use a new key
`invoice_already_exists`	409	No — the receipt number is already filed

Authentication and authorization

Code	HTTP	Retry?
`invalid_api_key`	401	No
`api_key_revoked`	401	No — issue a new key
`mode_mismatch`	403	No — use the right key
`insufficient_scope`	403	No — use a key with the scope

Fleet and configuration

The caller’s setup is incomplete. Each of these blocks fiscalization until someone changes something.

Code	HTTP	Retry?
`hr.device_missing_isu`	400	No — get the ISU number from ePorezna
`device_inactive`	400	No — reactivate the device
`company_missing_certificate`	400	No — upload a certificate
`certificate_expired`	400	No — upload a current certificate
`hr.certificate_oib_mismatch`	400	No — upload the right certificate

Croatian restrictive errors

Validated locally, before anything leaves our network, so you get a precise error in milliseconds instead of a round trip and an opaque upstream code.

Code	HTTP	Upstream rule
`hr.sale_older_than_30_days`	400	176
`hr.date_in_future`	400	177
`hr.invalid_receipt_number`	400	178
`hr.invalid_oib`	400	179, and 180 on an attended receipt
`hr.invalid_vat_rate`	400	182
`hr.invalid_pnp_rate`	400	183, 184
`hr.invalid_payment_method`	400	§2.2.1, §2.1.1, and 181 on an attended receipt
`hr.amount_out_of_range`	400	v185
`hr.tax_line_inconsistent`	400	none — ours
`hr.total_mismatch`	400	none — ours

hr.tax_line_inconsistent and hr.total_mismatch are the two entries with no upstream rule behind them, and they are a pair: one asks whether a tax line fits its own base, the other whether those figures describe the receipt at all. The Tax Administration verifies no arithmetic at all — a receipt whose VAT line reads 25% of 10.00 = 5.50 is well-formed, gets a JIR, and is wrong only in your books, where it can no longer be amended. We refuse it rather than file it.

Restrictive errors 180 and 181 judge OibPrimateljaRacuna, which is not part of the unattended message at all. They are dormant for unattended sales and live for attended receipts.

Upstream

These appear inside a 200 invoice body as fiscal_error, not as HTTP errors. The sale is valid in every case.

Code	Where	Retried automatically
`upstream_unavailable`	`fiscal_error` on a `200`	Yes
`upstream_rejected`	`fiscal_error` on a `200`	No — needs correction
`upstream_signature_invalid`	`fiscal_error` on a `200`	No — contact support

Rate limiting

Code	HTTP	Retry?
`rate_limited`	429	Yes — after `Retry-After`, with the same `Idempotency-Key`

Internal

Code	HTTP	Retry?
`internal_error`	500	Yes — with the same `Idempotency-Key`