Ingest API Errors and Limits

Every Ingest API error body, rate limit, size limit, pagination rule, and versioning rule is listed here, so you can keep this page open while you integrate. The full Ingest API reference covers the endpoints themselves.

Errors

Every error body is an RFC 9457 problem document served as application/problem+json, with the fields type, title, status, detail, instance, and often errors, which names each failed field.

Branch on type, never on detail. The set of types is closed and stable, so a client can match on it exhaustively. detail is written for a person and may be reworded between releases. instance is the request id: quote it when you contact support.

Status	`type`	Meaning
400	`bad-request`	The request could not be parsed.
401	`unauthenticated`	No credential was presented.
401	`token-expired`	The token's lifetime has elapsed. Request a new one.
401	`token-invalid`	The token's signature, issuer, or audience was not accepted.
403	`credential-not-provisioned`	The credential is not linked to a Leasecake workspace.
403	`client-not-granted`	The workspace has not granted this client, or revoked the grant.
403	`insufficient-scope`	The credential lacks the permission this endpoint requires.
403	`organization-inactive`	The workspace behind the credential is no longer active.
403	`membership-inactive`	Portal only. The signed-in person no longer belongs to the workspace.
403	`session-not-scoped`	Portal only. The session is not scoped to a workspace that may submit.
403	`csrf-token-mismatch`	Portal only. A session request carried no valid CSRF token.
404	`submission-not-found`	No such submission in your workspace.
4xx	`request-refused`	Refused outright: a portal session posting a lease, or a method or path this environment does not serve.
409	`idempotency-key-reuse`	The key was used with a different body. Generate a new key.
409	`idempotency-key-in-flight`	An identical request is still running. Retry after `Retry-After`.
409	`lease-already-exists`	A lease already carries this `external_lease_id`.
409	`item-not-answerable`	The item is not waiting on your answer.
409	`source-not-mappable`	The item was not handed off for mapping.
413	`payload-too-large`	The body exceeds what the endpoint will read.
422	`validation-failed`	The request was understood but rejected. `errors` names each field.
429	`rate-limited`	Too many requests. Wait for `Retry-After`.
500	`internal-error`	Leasecake could not complete the request. Retrying may succeed.

Each type is a full URI under https://leasecake.cloud/problems/. A 403 or 404 never confirms that a resource exists in another workspace.

Rate limits

The limits are 300 requests a minute per credential and 300 requests a minute per source address, and the address limit is shared by everyone behind the same outbound IP. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; pace your client against them instead of running into the limit. Over the limit, requests answer 429 with Retry-After in seconds.

Size limits

Limit	Value
Files per submission	25
Size of one file	100 MB
Total size of a submission	280 MB
Posted lease JSON	3 MiB
Documents sent with one posted lease	24
Size of a submission's `items` part	256 KB
Entries in one metadata object	20, 500 characters each

The failure mode differs by limit, and the difference decides what your retry should do:

A file over 100 MB is still accepted and held as oversize, so the rest of its batch goes through.
A submission over 280 MB is refused with 422 and nothing is recorded, so retry the same submission unchanged.
A body too large to read at all is refused with 413.

Pagination

Lists are cursor-paginated, newest first. Set limit (1 to 100, default 25) to size a page, pass each response's next_cursor back as cursor for the next one, and stop when it is null. Treat the cursor as opaque: never build or edit one.

Versioning

The major version sits in the path. Breaking changes ship under a new prefix, and v1 keeps working. Within v1, additive changes ship without notice: new optional request fields, new response fields, and new enum values.

Build your client open on responses: ignore unrecognized properties and never fail on an unknown enum value. The API maps unknown values to these fallbacks:

Field	Fallback for unknown values
`outcome`	`processing`
`quarantine_reason`	`needs_triage`
`failure_reason`	`processing_failed`
`extraction_failure`	`unreadable`
`resolved_kind`	`supporting_document`
`classification.document_class`	`unsupported`

Problem documents are the exception and stay closed: their type set does not grow, so a client may match on it exhaustively.

Requests are strict. An unknown top-level property on a submission or an item is refused; put round-trip data in an item's metadata instead.

Was this helpful?