Errors and retries

Check both the HTTP status and the submission body. An invoice rejected by
validation can return HTTP 200 with accepted: false and rule findings in
errors. Treat it as rejected until accepted and the relevant
clearance/reporting result confirm success.

HTTP status	What to check
`400`	Missing routing header or an account change blocked by active devices.
`401`	Missing, malformed or invalid `Authorization: Api-Key <key>`.
`404`	Account, device or document does not exist in your organization's scope.
`409`	Duplicate taxpayer VAT registration, missing/ambiguous signing device, or an incomplete compliance registration.
`422`	Invalid request fields, unsupported values or inconsistent invoice data.
`502`	NBR transport or upstream error. Inspect `nbr_error`, `nbr_status` and `message` when present.

The response's detail explains the specific failure. Compliance-registration
errors can carry BR-BH findings or the saved connected_account_id for recovery.

Validation findings

Wafeq checks the signed document against UBL XSD and Bahrain rules before sending
it. A failed local validation is recorded as ERROR and does not reach NBR.
Findings identify their rule codes; local failures use category
LOCAL_VALIDATION. Correct the data and validate again. Preserve NBR's returned
errors and warnings in your integration so the operator can see what needs
attention.

Retrying

An accepted document is identified by its connected account, document family
and document_number. Sending that same identity again returns the stored
accepted result with duplicate: true; it is not sent to NBR again. The
original accepted content is immutable: changing the payload while reusing its
number does not replace it. Use a new document number for a different document.

If a submission did not reach a terminal state, retry the stored document:

curl -X POST "$BASE/invoices/$DOC_ID/retry" \
  -H "Authorization: Api-Key $KEY"

Use its own family for simplified invoices, notes and prepayment invoices.
Retry resends the original signed XML through its original device; it does not
reassemble or resign the invoice. An already accepted document is returned
unchanged. A revoked device or one without production credentials returns
409. Renewing the device does not rewrite previously signed XML; NBR can
reject XML signed with its earlier certificate.

A rejected document can be corrected and submitted again under the same
document_number. After a timeout, inspect the stored status before deciding
whether to retry the stored submission or correct its data.