Errors

One shape for every failure. code is stable and safe to branch on; retryable: true means the same request (same Idempotency-Key) may be sent again; hint is written for whoever — or whatever — is integrating.

{
  "error": {
    "code": "date_before_last_document",
    "message": "Document date is earlier than the last document of the same type.",
    "message_he": "התאריך מוקדם מהמסמך האחרון מסוג זה.",
    "hint": "Israeli sequence rule: use details.last_document_date or later.",
    "retryable": false,
    "doc_url": "https://api.chat-invoice.co.il/docs/errors#date_before_last_document"
  },
  "request_id": "5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e"
}

unauthorized401

Missing or invalid API key.
מפתח API חסר או לא תקין.
→ Send `Authorization: Bearer ci_live_…`. Keys are created in the app under Settings → Connections → API.

key_revoked401

This API key was revoked.
מפתח ה-API בוטל.
→ Create a new key in the app.

subscription_required402

The business has no active paid subscription.
לעסק אין מנוי פעיל.
→ The API is available to paying subscribers. `details.payment_url` opens the subscription page.

business_archived403

The business is archived.
העסק בארכיון.
→ Contact support.

business_profile_incomplete403

The business profile is missing its legal type.
פרופיל העסק חסר סוג-עוסק.
→ Complete the business profile in the app (legal type / tax id).

external_provider_not_supported403

This business issues documents through an external accounting provider; the API supports native businesses only.
העסק מפיק דרך ספק חיצוני — ה-API תומך בעסקים שמפיקים אצלנו בלבד.
→ Not available for this business.

issuing_blocked_expenses_only403

The business is on an expenses-only track and cannot issue documents.
המסלול של העסק כולל ניהול הוצאות בלבד.
→ The accounting office must upgrade the track.

insufficient_scope403

The API key does not have the required scope.
למפתח אין הרשאה לפעולה זו.
→ Scopes: documents:write, documents:read, customers:read.

not_found404

Resource not found.
לא נמצא.
→ Ids are scoped to the business of the API key.

customer_not_found404

customer.id does not belong to this business.
הלקוח לא נמצא בעסק.
→ Use GET /v1/customers?q= to find the id, or send customer.name instead.

based_on_not_found404

based_on document not found in this business.
מסמך המקור לא נמצא.
→ Use the `id` returned when the source document was created, or GET /v1/documents.

invalid_json400

Request body is not valid JSON.
גוף הבקשה אינו JSON תקין.
→ Send `Content-Type: application/json`.

validation_error400

Request failed schema validation.
הבקשה לא עברה ולידציה.
→ See details.errors[] (path + message). Unknown fields are rejected — never send document numbers, VAT rate, totals or allocation numbers.

missing_idempotency_key400

Idempotency-Key header is required for POST /v1/documents.
חסרה כותרת Idempotency-Key.
→ Send a unique string per logical document (e.g. your order id + attempt). Retries with the same key return the same document instead of issuing twice.

invalid_customer_tax_id400

customer.tax_id failed the Israeli checksum.
ח.פ/ע.מ/ת.ז של הלקוח לא תקין.
→ Fix the number or omit it (a document above the allocation threshold will then be issued without an allocation number).

idempotency_key_reused409

Idempotency-Key was already used with a different request body.
מפתח ה-Idempotency כבר שימש לבקשה אחרת.
→ Use a new key for a new document.

request_in_progress409 · retryable

A request with this Idempotency-Key is still being processed.
בקשה עם אותו מפתח עדיין בעיבוד.
→ Retry the same request in a few seconds; you will get the stored result.

customer_identity_conflict409

customer.tax_id belongs to a differently-named customer of this business.
הח.פ רשום על לקוח אחר בכרטסת.
→ Either send customer.id = details.existing_customer_id, or set customer.identity_confirmed=true to open a separate card.

legal_type_forbidden422

This business type may not issue the requested document type.
סוג העוסק אינו רשאי להפיק מסמך מסוג זה.
→ GET /v1/document-types lists what this business may issue. An exempt dealer (osek patur) issues receipts / proforma invoices instead of tax invoices.

payments_required422

This document type requires payments.
סוג מסמך זה דורש פירוט תשלומים.
→ Add payments[] summing to the total, or use tax_invoice / proforma for an unpaid document.

payments_not_allowed422

This document type does not carry payments.
סוג מסמך זה אינו כולל תשלומים.
→ Remove payments[], or use tax_invoice_receipt / receipt.

payments_total_mismatch422

payments[] do not sum to the document total.
סכום התשלומים אינו שווה לסה"כ המסמך.
→ details.total is the computed total; make payments sum to it (±0.01).

discount_not_allowed422

Receipts do not carry a document discount.
קבלה אינה כוללת הנחה.
→ Remove discount.

based_on_required422

credit_note requires based_on (the invoice being credited).
חשבונית זיכוי דורשת מסמך מקור.
→ Send based_on = id of the tax_invoice / tax_invoice_receipt.

based_on_type_not_allowed422

based_on document type cannot be the source of this document type.
סוג מסמך המקור אינו מתאים.
→ See details.allowed_source_types.

based_on_cancelled422

based_on document is cancelled.
מסמך המקור מבוטל.

total_mismatch422

Computed total differs from expected_total; nothing was issued.
הסה"כ המחושב שונה מהצפוי — לא הופק.
→ details.computed_total shows our figure (VAT from the business settings). Fix your figures or drop expected_total.

future_date422

Document date cannot be in the future.
לא ניתן להפיק מסמך בתאריך עתידי.
→ Use today (Israel time) or earlier.

date_before_last_document422

Document date is earlier than the last document of the same type.
התאריך מוקדם מהמסמך האחרון מסוג זה.
→ Israeli sequence rule: use details.last_document_date or later.

use_credit_note422

Accounting documents cannot be cancelled; issue a credit note (or a refund receipt) instead.
מסמך חשבונאי לא מבוטל — מפיקים חשבונית זיכוי.
→ POST /v1/documents with type=credit_note and based_on=this id (same items).

already_cancelled422

Document is already cancelled.
המסמך כבר מבוטל.

linked_document_closed422

A delivery/return note that was already invoiced cannot be cancelled.
תעודה שכבר חויבה לא ניתנת לביטול.
→ Credit the invoice first.

rate_limited429 · retryable

Too many requests.
יותר מדי בקשות.
→ Respect Retry-After and X-RateLimit-* headers.

daily_limit_reached429

Daily document limit for this API key reached.
הגעת למכסת המסמכים היומית של המפתח.
→ Resets at midnight Israel time. Contact support to raise the limit.

document_generation_failed502 · retryable

The document could not be rendered; the sequence number was rolled back.
הפקת המסמך נכשלה; המספר שוחרר.
→ Safe to retry with the same Idempotency-Key.

engine_error502 · retryable

Document engine error.
שגיאת מנוע.
→ Retry with the same Idempotency-Key. If it persists contact support with request_id.

api_disabled503 · retryable

The API is temporarily disabled.
ה-API מושבת זמנית.
→ Retry later.

payload_too_large413

Request body exceeds 256KB.
גוף הבקשה גדול מדי.
→ Max 100 items, 1000-char notes.

internal_error500 · retryable

Unexpected error.
שגיאה לא צפויה.
→ Retry with the same Idempotency-Key; contact support with request_id.