Error Handling

The Glance API uses standard HTTP status codes, and every failure carries a machine-readable code alongside a human message. Branch on the code, not on the message — the message is Hebrew and is written for a person to read.

Error Response Format

{
  "success": false,
  "error": {
    "status": 404,
    "code": "DOCUMENT_NOT_FOUND",
    "message": "המסמך לא נמצא"
  }
}

Validation failures add an issues array — the Zod issues for the fields that failed:

{
  "success": false,
  "error": {
    "status": 400,
    "code": "INVALID_FIELD",
    "message": "שדה לא תקין",
    "issues": [
      {
        "path": [
          "products",
          0,
          "price"
        ],
        "message": "price must be zero or greater"
      }
    ]
  }
}

One older shape. A few endpoints — the internal note, the execution status, and the identifier checks on document creation — answer with a bare { "error": { "code", "message", "issues" } } and no success key. Read error.code and you handle both shapes.

HTTP Status Codes

Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request body or parameters
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	API key lacks required permissions
`404`	Not Found	Resource does not exist
`409`	Conflict	Idempotency-key conflict, or a resource that already exists
`429`	Too Many Requests	Rate limit exceeded — see Rate Limits
`500`	Internal Server Error	Something went wrong on our end

Common Error Codes

Code	Status	When
`NO_ACCESS`	403	The key cannot reach this company or this action.
`INVALID_FIELD`	400	Body validation failed — see `issues`.
`DOCUMENT_NOT_FOUND`	404	No document with that visibleId, externalId or related id.
`DOCUMENT_CLOSED`	400	The target document is already settled.
`INVALID_STATUS`	400	The operation does not apply in the document's current state.
`INVALID_DOCUMENT_TYPE`	400	Unknown `type` filter — the response names `invalidTypes` and `supportedTypes`.
`INVALID_CURSOR`	400	The change-feed cursor was not one we issued.
`INVALID_UPDATED_SINCE`	400	`updatedSince` is not a valid ISO 8601 date.
`INVALID_EXTERNAL_ID`	400	`externalId` is empty or longer than 64 characters.
`INVALID_IDEMPOTENCY_KEY`	400	`Idempotency-Key` is not a string, or exceeds 255 characters.
`IDEMPOTENCY_KEY_REUSED`	409	The same key was already used for a different request body.
`REQUEST_IN_PROGRESS`	409	A request with this key is still being processed.
`RATE_LIMITED`	429	Over the per-key limit — the body carries `retryAfter`.

Tip: check error.issues for field-level detail before retrying a 400 — the same body will fail again.

Retrying a failed write. A 4xx or 5xx on document creation releases the Idempotency-Key, so you may fix the body and retry with the same key. Never retry a create without one — see Idempotency.