What each API error code means

The invoicing API lets another program create invoices and credit notes, post them, read their state and PDF, and validate a tax number (NIF). All responses have the same shape, with no technical server errors. This article is for whoever builds or maintains that connection: people who use fiscaldoo on screen do not see these codes, only the system messages.

What a response looks like

{"ok": false, "code": "VAT_INVALID", "message": "O NIF não é válido: tem de ter exatamente 9 dígitos (0-9) e o dígito de controlo correto. Corrija o NIF e envie-o de novo.", "data": {}}

• ok: true if the operation was done. When it is false, nothing was saved.
• code: OK or one of the codes below. This is the field the program should test.
• message: the explanation in Portuguese, to show to a person. Its wording may change: do not compare it in the program.
• data: the document's data, when there is any.

The codes

The messages below are real API responses, obtained with calls to the demo database. The parts in italics change from case to case.

Code	What it means	Message	What to fix
ACCESS_DENIED	The connection's user does not have the permission.	“Your user is not allowed to use the invoicing API: it requires the permission “API Integration”. Ask a fiscal administrator to give it to the integration user.”	Give the permission: see below.
NOT_FOUND	The document does not exist in the company the call runs in. A document from another company gives the same response.	“The document was not found in the current company. Check the identifier and the company.”	Check the identifier and the company of the call.
INVALID_INPUT	A value sent cannot be used. The message says which.	“Unknown or not allowed fields: cor.”; ““quantity” must be a number.”; ““lines” must be a list of 1 to 200 lines.”	Correct the value and send it again.
VAT_INVALID	The tax number sent is not valid.	“The VAT number (NIF) is not valid: it must have exactly 9 digits (0-9) and a correct check digit. Correct the NIF and send it again.”	Correct the tax number.
PARTNER_NOT_FOUND	The customer does not exist in the call's company, or the tax number does not point to a single customer.	“The customer was not found in the current company.”; “No single customer with this NIF was found in the current company. Create the customer first or send “partner_id”.”	Check the company. Create the customer or send their identifier.
NOT_PUBLISHABLE	The document is no longer in draft.	“Only a draft document can be published. What happened: this one is already “Posted”. How to fix it: send a document that is still in draft.”	Do not post it again. Read the document's state.
NOT_POSTED	You asked for the PDF of a draft.	“Only a published document has a PDF; publish this one first.”	Post the document and ask for the PDF afterwards.
BUSINESS_RULE	The operation goes against a product rule or the law. The text comes from the rule that refused it and may list several missing items.	“3 things are missing to confirm this invoice: …”, with Why and What to do for each missing item.	Read the list and fix each point. A missing series is solved in fiscaldoo, not in the program.
VALIDATION_ERROR	A value does not meet a validation rule. The text comes from the rule.	No fixed sentence.	Read the message: it states the rule and the value.
PDF_UNAVAILABLE	The PDF could not be produced at that moment.	No sentence copied.	Try later. If it continues, contact support.
INTERNAL_ERROR	Unexpected failure on the server side. Nothing was saved.	No sentence copied: the message carries a reference.	Try again. If it continues, give the reference to support.

Pending validation on screen: VALIDATION_ERROR, PDF_UNAVAILABLE and INTERNAL_ERROR were not triggered in the demo. The wrong values we sent were refused earlier, with INVALID_INPUT, and the other two require a server failure. That is why we do not quote their sentences here.

The integration permission

Who does it: an Administrator.

1. Open Settings › Users & Companies › Users and open the integration user.
2. In the Advanced settings tab, under PT Localization — API Integration, choose API Integration.
3. Click Save.

Use a dedicated user for the connection: this permission includes invoicing. On the next call, ACCESS_DENIED no longer appears.

The call's company

Each call runs in a single company, the user's. A document or a customer from another company responds NOT_FOUND or PARTNER_NOT_FOUND, as if it did not exist: the program never learns what there is in the other companies. If an identifier you see on screen gives NOT_FOUND, check the company first.

In file downloads

A report or a statement opened through a direct address responds differently, with a plain text page and the code at the end:

“The record was not found. It may have been deleted, or it belongs to another company. Reload the screen and check the company selected at the top.

(NOT_FOUND)”

It has the same meaning as the API's NOT_FOUND.

When to contact support

• Repeated INTERNAL_ERROR, or PDF_UNAVAILABLE that does not go away.

Follow How to ask support for help and what information to send, with the code, the method called and the reference, if there is one. Never send the integration user's password.