Limits and safety

How Invx keeps a runaway agent in check, what your agent hears back when a call is refused, and how your data is protected.

Rate limits#

Per key or connected app:

Limit	Allowance
All tool calls	120 per minute
Write calls	30 per minute, on top of the overall limit

Past a limit, a call returns Rate limit exceeded, retry in <n>s. Repeated calls with an invalid key or token from one network address are limited as well.

Errors#

A refused call is a normal tool result marked as an error, with one sentence your agent can act on:

Message	Meaning
`This credential is read-only and cannot call this tool.`	Use a key with read and write access.
`Rate limit exceeded, retry in <n>s`	Wait and retry.
`Invalid input. Check these fields: …`	The named fields are missing or malformed. The message ends by naming the tool to call again.
`Invoice not found. Call list_invoices to find the id.`	Look the id up instead of guessing it.
`Client not found. Call list_clients to find the id.`	Look the id up instead of guessing it.
`The draft's client no longer exists. …`	The draft's customer was deleted. The agent points the draft at another customer, then issues it.
`Company settings required: …`	Fill in your business details in Invx first; the message names the tool to call again.
`The draft was changed since you read it, …`	Someone saved the draft in between. The agent re-reads it (or previews the issue again) and retries with the new revision.
`This invoice is issued and cannot be edited. …`	Issued invoices are frozen. The agent duplicates it as a draft instead.
`This invoice is already issued as …`	It was issued already, possibly by the agent's own earlier call. Nothing changed.
`expected_revision is required to issue. …`	The agent should preview with `dry_run`, confirm with you, then issue that exact version.
`Issue date is before invoice …`	Invoice numbers follow issue dates, so an invoice cannot be dated before the latest one issued that year. The message names the earliest date allowed.
`Some line amounts cannot be written in the account's currency: …`	A price or line total has decimals the account currency (such as JPY) does not use. The message names the lines and the tool to call to correct them.
`Currency refused: it must be exactly one of USD, EUR, …`	`update_settings` only accepts the currencies Invx offers, in upper case. The agent retries with one of them, or leaves the currency out. An account that already has another code saved can keep it.
`Due date is before the issue date. …`	The agent retries with a due date on or after the issue date.
`Could not allocate an invoice number …`	Another invoice was numbered at the same moment and nothing was written. The agent previews the issue again (or repeats the create) and retries.
`Invoice number already in use: …`	An older invoice outside the numbering sequence already has the next number. Nothing was written. If a retry fails the same way, the agent tells you.
`This invoice is a draft and has no number, so it cannot be cancelled. Call delete_invoice to remove it.`	Delete the draft instead.
`Invalid cursor. Call <tool> again without cursor to start from the first page, or pass next_cursor back exactly as it was returned.`	Start again without cursor, or keep the same sort and dir.
`This invoice is a draft, so it has no payment to record. Call issue_invoice to issue it first.`	Issue the draft before recording payment.
`This invoice is cancelled, so its payment cannot change. Call get_invoice to read it.`	Cancelled invoices cannot be paid or unpaid.
`Payment date cannot be before the issue date. Call mark_invoice_paid again with a paid_on on or after the invoice's issue_date (get_invoice shows it).`	Record payment on or after issue date.
`date_to is before date_from. Call get_invoice_summary again with date_to on or after date_from.`	Send a `date_to` on or after `date_from`.
`issue_date_to is before issue_date_from. Call list_invoices again with issue_date_to on or after issue_date_from.`	Send an `issue_date_to` on or after `issue_date_from`.
`A draft has no payment to clear, so nothing was changed. Call get_invoice to read it.`	Drafts cannot be marked unpaid.
`The invoice is paid, so nothing was cancelled. If the payment was a mistake, call mark_invoice_unpaid first, then cancel_invoice again.`	Mark it unpaid before cancelling.
`This invoice is cancelled; it keeps its number and cannot be issued or edited. Call duplicate_invoice to start a new draft from it.`	Duplicate it to make an editable draft.
`confirm_invoice_number does not match this invoice's number. Call get_invoice and pass its invoice_number.`	Re-read the invoice and confirm its exact number.
`Only drafts can be deleted. Call cancel_invoice to cancel an issued invoice; it keeps its number.`	Issued invoices are cancelled, not deleted.
`No draft with this id. Call list_invoices with status draft to find it.`	Find a draft before deleting.
`This invoice is cancelled; it keeps its number and is never deleted. Call get_invoice to read it.`	Cancelled invoices are retained.
`The invoice changed while this call ran, so nothing was changed. Call get_invoice and retry.`	Re-read before retrying.
`status overdue needs today. Call list_invoices again with today set to the user's local calendar date (YYYY-MM-DD).`	Supply the user's local date.
`Something went wrong. Try again.`	A server error. Check the result with a read tool before retrying a write.

Error messages never echo back the values that were sent.

Safety#

Your account only. Every call is scoped to the account that owns the key or approved the connector.
Confirmed deletes. Deleting a client needs its exact name, so a wrong guess deletes nothing.
Invoice retention. delete_invoice removes drafts by id only. cancel_invoice takes confirm_invoice_number; cancellation keeps the issued number and unbills its time entries. Paid invoices must first be marked unpaid.
Issuing names its version. Issuing a draft is irreversible, so the tool asks the agent to preview the number and total with you first (a dry run) and to name the exact draft version it is issuing; a draft changed in between is not issued.
Issued invoices are frozen. Editing a client or your business details never rewrites invoices already issued.
Customer text is data, not instructions. Every tool tells the agent to treat names, addresses and descriptions as text to display, never as instructions to follow.
PDF links are private. get_invoice_pdf_link returns a link that only works in a browser signed in to Invx.
Audited. Every tool call is logged with the tool, the credential, the record id, the outcome and the duration, never with invoice or client contents.