Errors and Refusal codes

What kind of error it is — one of the error types. Branch on this.

What went wrong, in words for a person, in the words Essentio’s own screens use.

With a 422 invalid_request whose fields the rules refused: each field, parameter or header at fault, with a list of what is wrong with it.

With a refusal: the Refusal code that says why.

With some refusals: what the Business does in Essentio to open the Action — one of the remedies.

When a Send issued its Draft and then did not go out (not_delivered, or the refusal mail_account_lost): the Document number the Draft took. It stays issued.

With the remedy record_on_its_invoice: id and document_number of the Invoice that takes the Payment instead.

The request carries no API key or access token, an unknown one, or one that no longer acts: a revoked key, an expired token, or a Connected app that ended. See Authentication.

The credential’s Role may not do this: an API key’s, or the Role a Connected app acts with now — or the Business’s plan does not let it, and then code says why. It is asked before the record the request names, so a Role that may not make a change is answered permission whatever id it sends, one that names nothing included.

No such endpoint, or the Business has no record with this id. A record of another Business is not found either.

Any other request the API cannot answer as sent. A 422 names each field, parameter or header at fault in errors, in the words Essentio’s own forms use — a decimal sent as a JSON number, a limit out of range, a cursor the API did not give.

An Idempotency-Key sent again with another request than the first one under it. Nothing was done. See Idempotency.

The first request under this Idempotency-Key is still being performed. Nothing was done; send the same request again in a few seconds to read its answer.

The API key or Connected app made more requests this minute than its limit allows. Nothing was done; wait Retry-After seconds. See Rate limits.

The Action is refused for the document or Payment as it stands. code says why; nothing was written.

The mail provider did not accept a Send’s email, or could not be reached in time. The request was sound.

A fault on Essentio’s side.

Only a Draft is issued; this document already has its number.

The Document number the Draft asks for (requested_document_number) is already taken by another document.

The requested number skips ahead of the numbering; message names the next one.

The requested number ends in a number larger than the numbering can count to.

The requested number is not a valid Document number.

The next number — a document's, or a Receipt's — is the largest the numbering holds, which it never takes, because it cannot count past it; message names that number. Nothing is written. A Draft can still be issued with an unused earlier number sent as its document_number; a Receipt has no such way out.

A Cancelled document is not sent.

The Client has no email address. Nothing is issued.

The Business has nothing to send through: it sends through Essentio's own mail server unless it connected a mailbox, and it has no email address of its own for replies (remedy connect_mail_provider). Nothing is issued.

The Business’s connected mail account refused to renew its access (remedy connect_mail_provider).

The Business sends through Essentio's own mail server, which emails a limited number of recipients for it a day — To, Cc and Bcc each count: 20 on the Free plan, a Test business and a Paused Business, 100 on Pro, 200 on Pro Plus — and this email does not fit what is left; message says how many are (remedy connect_mail_provider: its own mailbox has no such limit). Once none is left a Draft is not issued; a Send refused after it issued its Draft names the number in message.

A Draft is not a document yet; it is deleted instead (DELETE /v1/documents/{id}).

A Paid document is corrected with a Credit Note.

The document is already Cancelled.

The document holds Payments (or its Proforma’s); it is corrected with a Credit Note.

Only a Proforma Invoice converts into an Invoice.

A Draft Proforma Invoice is issued first.

A Cancelled Proforma Invoice converts into nothing, so neither is it converted nor is a Draft still linked to it saved, which would issue it.

An Invoice was already made from this Proforma Invoice.

Only a Draft is deleted; an issued document is cancelled instead.

A Credit Note or a Quote takes no Payments; message says why.

A Draft is issued first.

A Cancelled document takes none.

The document’s Amount due is zero.

The Proforma Invoice was converted into an Invoice, which takes the Payment (remedy record_on_its_invoice with error.invoice, while that Invoice still takes one).

currency is not the document’s.

The amount is above what is due.

It was reversed already.

Only a Draft is changed through the API; an issued document is changed in Essentio.

The Draft was deleted meanwhile, by another request made while this one waited for it. Nothing is written and no number is taken.

The Draft is linked to a Proforma Invoice that was deleted, so nothing is converted from it and its save, which would issue it, is refused.

The Draft is linked to a Proforma Invoice, and only an Invoice is made from one.

The Draft is linked to a Proforma Invoice in another currency; message names it.

The Draft is linked to a Proforma Invoice of another Client.

The document is not exported as EN16931 XML (a Draft, a Proforma Invoice, a Quote, or one the EN16931 check does not pass); message says why.

The Business is a Test business (is_test), which keeps no real books, so it exports nothing an accountant books from. Its PDFs stay, marked SAMPLE.

The credential’s Role may not take the Action. Taken anyway, it is a permission failure (403), not a refusal.

The Business is on the Free plan or Paused, and the Public API needs a paid plan, so every API key and Connected app of the Public API is refused whatever it asks, a read included. It is a permission failure (403) carrying this code and the remedy choose_plan; message says whether the Business is on the Free plan or paused. Nothing is revoked: the same credential works again once the Business is on Pro or Pro Plus. It comes before any other answer, so the Public API never answers business_paused or plan_role_viewing.

The Business is Paused, because its Owner’s plan does not cover it; it still reads everything and records Payments. Taken, it is a permission failure (403) carrying this code and the remedy choose_plan; a document’s actions answer it too. The Public API refuses a Paused Business’s credentials paid_plan_required first.

The Business is on the Free plan, where everyone but its Owner only reads, and so does every Connected app they authorised; the Owner’s own Connected app is cut by nothing but the Role it was given. Taken, it is a permission failure (403) carrying this code and the remedy choose_plan; a document’s actions answer it too. The Public API refuses a Free Business’s credentials paid_plan_required first.

The document is another Business’s. On the API another Business’s record is not_found (404).

The Business is on the Free plan, or is a Test business, and has issued its Invoices for this year; message names the day it issues again (remedy choose_plan). On the MCP server only a Free Business’s Owner’s own Connected app issues, so it meets this; anyone else’s meets plan_role_viewing first, and the Public API answers a Free Business paid_plan_required first. A Test business keeps the Public API on every plan and meets it there too, in its own words and with no remedy: a reset lets it issue again.

The Business has nothing to send through — no mailbox connected and no email address of its own for Essentio's mail (remedy connect_mail_provider).

Reminders go only for issued documents still unsettled.

A Credit Note or a Quote is never reminded about; message says why.

The Proforma Invoice was converted into an Invoice, which is reminded about instead.

The Payment was reversed, so its Receipt is void.

The Business has nothing to send through — no mailbox connected and no email address of its own for Essentio's mail (remedy connect_mail_provider).

The Payment has no Receipt.

The document’s Client was deleted.

The amount is not above zero. The API refuses that amount as invalid_request first.

The amount is finer than its currency’s minor unit. The API refuses that amount as invalid_request first.

A Cancelled document is not edited.

The document takes no correction of its number as it stands.

The Proforma Invoice it names is not found.

A Draft is issued first.

A Cancelled document is not marked as sent.

A Cancelled document keeps its delivery mark.

The document is not marked as sent.

The Webhook is paused.

The app no longer hears the Business the message is about.

The Business the message is about is on the Free plan or Paused, and Webhooks need a paid plan.

The request is Essentio support’s, which reads a Business with its Owner’s Support access and changes nothing. No credential of the API or the MCP server is support’s.

In Settings → Email, connect a mailbox of the Business's own (or connect the lost account again); for no_mail_provider, adding the Business's email address in Settings → General lets Essentio send again, and for sending_limit_reached the next day does.

The Proforma Invoice was converted into an Invoice, which carries the debt: record the Payment on that Invoice (error.invoice) instead.

The Business’s plan does not let it (business_paused, plan_role_viewing, paid_plan_required, webhooks_need_a_paid_plan, issuing_limit_reached): its Owner chooses a plan in Settings → Billing.