Format#
Native endpoints answer errors as:
{ "error": "invalid API key" }The Invoice4U-compatible shape of create-document answers in its own envelope, still with the real HTTP status:
{ "d": { "IsSuccess": false, "ErrorMessage": "auth failed" } }(calculate always uses the plain {"error": …} form, even for the compatible request shape.) Messages are written for the caller and are safe to log. Internal failures are logged on our side and reach you only as a generic message.
Status codes#
| Status | Meaning | Typical body |
|---|---|---|
| 200 | Success. Also returned for an idempotent repeat (alreadyExisted: true). | |
| 201 | Sandbox account created. | |
| 400 | The request body is not valid JSON. (Sandbox signup: invalid email / short password / disposable domain.) | {"error":"invalid JSON"} |
| 401 | Unknown, revoked, missing or over-long API key; a closed business. | {"error":"invalid API key"} · compat auth failed |
| 403 | The account is dormant: billing is not switched on, so writes are refused. | {"error":"billing module is dormant (billing_enabled=0)"} |
| 404 | GET /documents?id= with an unknown id. | {"error":"not found"} |
| 409 | Sandbox signup: the email is already registered. | {"error":"…","code":"exists"} |
| 422 | The request was understood but refused: validation, a business rule or a plan gate. | {"error":"…"} |
| 429 | Rate limited: over 600 requests/minute for the key (or the per-IP limit on signup/receivers). No Retry-After on the API (sandbox signup sends one). | {"error":"rate limited"} |
| 502 | Connector receiver: fetching the full order from the platform failed; the platform should retry. |
Note that plan refusals are 422, not 402/403: the free plan cannot issue through the API, and past the monthly document allowance issuing is refused, both with a Hebrew message. Only the dormant-account refusal is 403.
422 messages from create-document (native shape)#
| Message | Cause |
|---|---|
document is required | document missing or not an object |
lines is required (non-empty array) · too many lines (max 500) · lines[i] is invalid | line list problems |
<field> must be an integer between <min> and <max> | non-integer or out-of-range money/quantity (vatBp, discountValue, withholdingAgorot, fxRateMillionths, lines[i].quantityMilli, lines[i].unitPriceAgorot, lines[i].discountValue, lines[i].vatBp, payments[i].amountAgorot) |
<field>: unsupported VAT rate 17% — only 0% (exempt) or 18% (statutory) are accepted | any vatBp other than 0 / 1800 |
payments must be an array · payments[i] is invalid | payments shape |
issueDate must be an ISO date YYYY-MM-DD | missing or malformed date |
issueDate must be between <date> and <date> | outside 30 days back / 1 day ahead |
apiIdentifier is required | blank apiIdentifier |
subject is required · customer name is required | empty subject / customer name |
a credit note must reference exactly one document · referenced document not found · a credit note can only reference an invoice/receipt, not another credit note · a credit note cannot reference a draft — the referenced document must be issued | credit-note references |
a quote cannot reference other documents | type 7 with referenceDocIds |
payments (<paid>) + withholding (<w>) must equal total (<total>) | payment documents (2, 3, 9, 11) |
payment amounts must be positive · enter withholding via withholdingAgorot, not as a payment row · withholding applies to payment documents only | payments / withholding rules |
document total must be positive · document amount exceeds the maximum | totals |
credit exceeds document total (<n> > <total>) · document is already fully credited/cancelled | crediting more than remains |
| Hebrew messages | return-note, purchase-order, self-invoice, foreign-currency and deposit rules of the newer document types (for example an exchange rate is mandatory for a non-ILS document) |
| Hebrew plan message | free plan can't use the API to issue / monthly allowance reached |
422 messages from the Invoice4U-compatible shape#
ApiIdentifier is required · Items are required · ClientName is required for DocumentType 1 (חשבונית מס / חשבונית זיכוי) — a tax document must identify the buyer · TaxPercentage: unsupported VAT rate … · Items[].TaxPercentage: unsupported VAT rate … · unparseable date: <value> · plus every engine message above. DocumentType: 4 cannot be issued in this shape (no way to name the invoice it credits): a credit note must reference exactly one document.
Other endpoints#
| Endpoint | 422 message |
|---|---|
POST /calculate | document.lines is required, or the compat mapper's message |
POST /customers | customer name is required (or create failed) |
Connector receivers#
POST /api/billing/ecommerce/{source}/{hookId}: 404 unknown hook (unknown connector or hook id — deliberately no hint which), 401 invalid signature / 401 <platform> secret is not configured for this business, 400 invalid body / missing order id, 413 payload too large (over 512 KB), 429 rate limited. Once hook and signature are valid the answer is 200 even if nothing was issued (skipped: …, duplicate: true) — business failures are recorded on the order in the dashboard.
MCP#
The MCP endpoint speaks JSON-RPC: 401 with error -32001 for a bad key, 429 with -32000, 400 with -32700 for unparseable JSON; a tool that fails at runtime returns HTTP 200 with result.isError: true. See mcp.
Handling errors well#
- 401: stop and alert; retrying will not help.
- 429: back off (exponential, start at a few seconds) and retry.
- 5xx / network error on
create-document: retry with the sameapiIdentifier— the call is idempotent, you will get the same document, never a duplicate. - 422: do not retry unchanged. Fix the payload (or, for plan messages, the plan). Because a failed first attempt releases its
apiIdentifier, a corrected retry with the same identifier succeeds.