Errors and warnings

Every problem is an object with a stable code, a severity, a scope, the field it concerns and params to fill your own message. Show your users your own text, keyed by code. message is English, for your developers and logs.

If you only send, you receive just the errors in the response to a call, under Refused on submit below, and VAT IT works through every other error with the client directly. The rest of the list is what the read endpoints return.

{
  "code": "counterparty_vat_number_invalid",
  "severity": "error",
  "scope": "document",
  "field": "counterparty_vat_number",
  "params": {"value": "PL70100014"},
  "message": "The VAT number does not match the format for PL"
}

New codes may be added. Existing codes are never renamed.

Scope

`scope`	Meaning
`document`	A document field is wrong, for example `counterparty_vat_number`. The problem shows on every line
`line`	This line alone, for example `lines[2].tax_code`
`lines`	Found on several lines checked together, for example a VAT total per rate that does not add up. It shows on each line involved

Refused on submit

The document is not stored. Fix it and resend.

Code	When
`field_missing`	A required field is absent
`field_invalid`	Wrong type, format or value
`total_sign_invalid`	The lines' `net` or `vat` add up to less than zero on an invoice, or more than zero on a credit note
`client_unknown`	`client_ref` is not one of your clients
`version_conflict`	Same `source_updated_at` as one VAT IT holds, with a different body
`stale_version`	Older `source_updated_at` than one VAT IT holds
`line_id_duplicate`	Two lines of the document share a `line_id`

Not yet matched to a registration

The line is unrouted. Most of these are fixed by VAT IT, and the line reprocesses on its own.

Code	When	Who fixes it
`client_not_onboarded`	Onboarding has not finished	VAT IT
`registration_not_active`	The client's registration in `tax_jurisdiction` is not active yet	Nobody. It reprocesses on activation
`no_registration_match`	The client has no registration in `tax_jurisdiction` that this tax code reports under, for example an OSS sale where the client has no OSS registration there	VAT IT checks; you if `tax_jurisdiction` or the code is wrong
`tax_code_not_valid`	The code does not exist, is retired, or does not apply in `tax_jurisdiction`	You
`tax_code_unmapped`	VAT IT has no mapping yet for your own code, or has not enabled the VAT IT code for `tax_jurisdiction`	VAT IT

Found when checked

The line is processed. An error blocks its return; a warning does not.

Code	Severity
`amounts_inconsistent`	error
`tax_rate_invalid`	error
`currency_conversion_failed`	error
`date_in_future`	error
`counterparty_vat_number_missing`	error
`counterparty_vat_number_invalid`	error
`counterparty_vat_number_unverified`	warning
`counterparty_country_invalid`	error
`counterparty_country_domestic`	warning
`possible_duplicate`	warning
`field_required_for_return`	error. `params` names the field the return needs
`field_invalid_for_return`	error
`processing_failed`	error, fixed by VAT IT

After filing

Code	When
`locked_filed`	A change arrived for a filed document. It waits for a correction
`correction_open`	VAT IT opened a correction and is applying the waiting version

Tax codes