> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywise.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Public limits

> API rate limits, resource limits, and how each is enforced.

[API rate limits](#api-rate-limits) control how many requests or actions you
can perform within a minute or hour. When an allowance is exhausted, wait
before retrying.

[Resource limits](#resource-limits) control the size, contents, and lifetime of
business records. Waiting does not increase these limits: correct the data,
reduce the batch, or free capacity as described below. The API reference also
lists limits beside the affected fields.

## API rate limits

Rate limits keep polling, bulk imports, and downloads within the capacity
available to a company or Partner. A request must fit **every applicable
allowance**, so having capacity for one operation does not bypass a shared
company or credential limit.

| Activity | Allowance | Shared by |
| - | - | - |
| Overall API requests | 600 per minute | Direct Case and Mahnservice: credential and company. Partner management: credential and Partner. Partner acting for a company through Case: credential, Partner, and selected company. |
| Writes to one operation | 120 per minute | That operation's additional request allowance. Reads have no per-operation allowance. |
| Test a webhook or manually redeliver one | 20 per hour, combined | The company, or the Partner for Partner-owned webhooks. |
| [Document](/api-docs/case-management-api/concepts/documents-and-communication) and [statement](/api-docs/case-management-api/concepts/statements) downloads | 120 per hour, combined | The company, across download operations and callers. |

Downloads include claim, message, answer, rental-agreement and title documents,
mandate documents, history and client-request attachments, and statements.
Partner requests on behalf of a company share that company's download allowance.
The two hourly allowances are checked before an operation starts and charged
only after a qualifying success: a `200` download or a `202` accepted test
event or redelivery counts, while a `404` poll of a document that is still
processing, a `HEAD`, or a rejected request does not. In-flight work does not
reserve capacity or appear in the usage response, so closely concurrent
successes can all pass the pre-check; do not treat the allowance as an
in-flight concurrency ceiling. Once the stored allowance is exhausted, later
requests answer `429` before the operation runs. Downloads negotiate on `Accept`: `*/*`, `application/octet-stream`,
`application/pdf`, `image/*`, and `application/json` are served, anything else
is `406 not_acceptable`; an object missing from storage is `404`, a storage
fault `503 service_unavailable` with `Retry-After`.
The Mahnservice and Case APIs share the per-token and per-company 600-per-minute
allowances. Every write additionally charges `endpoint:<basename>.<action>`
at 120 per minute. Mahnservice's `payments` and `documents` routes serve
reads and writes on one path: only `POST` charges
`endpoint:mahnservice-invoices.documents` or
`endpoint:mahnservice-invoices.payments`; `GET` charges only the shared principal allowances. The
Mahnservice API has no hourly expensive-operation allowances and no usage
endpoint.

**Enforcement:** an exhausted activity allowance returns `429 throttled`.
Wait at least the number of seconds in `Retry-After` before retrying. There are
no `X-RateLimit-*` response headers.

Read [Case usage](/api-docs/case-management-api/reference/usage/get-rate-limit-headroom)
or [Partner usage](/api-docs/partner-api/reference/usage/get-rate-limit-headroom)
to see capacity used, remaining capacity, and reset times. Usage and info are
ordinary reads: they consume principal capacity and can return `429`. Usage
includes its own request in the returned used count. The hourly counters are named `expensive:webhook-delivery`,
`expensive:document-download`, `mail:company-create`, and
`mail:membership-create` where applicable. See
[Errors and safe retries](/api-docs/essentials/errors-and-safe-retries) for
idempotency and retry handling.

### Company creation and invitations

Company creation and [membership invitations](/api-docs/partner-api/workflows/manage-memberships)
have additional **hourly rate limits**, shared by all credentials belonging to
the same Partner:

| Business activity | Allowance | What counts |
| - | - | - |
| Create managed companies | 30 per hour | Each successful company creation. |
| Add company memberships | 60 per hour | Each successful membership addition, including each entry in a new company's `users` array. |
| Resend a pending setup invitation | 5 per hour per membership | Requests to [resend the setup token](/api-docs/partner-api/workflows/manage-memberships). |

For the company-creation and membership-addition allowances, only a successful
command consumes capacity; rejected or failed requests and idempotent replays
do not. A request that would exceed either allowance returns `429 throttled`
with `Retry-After` and is rejected as a whole: no company or membership is
created and no mail is sent. For example, inviting five users during company
creation requires one available company creation and five membership additions.

<Accordion title="Protection against repeated authentication failures">
  On the Case Management API, a client IP may make at most **240 failed authentication attempts per minute**.
  Missing, unknown, suspended, or wrong-environment credentials returning
  `401` count. Valid-key company-context failures (missing, malformed,
  foreign, or revoked context returning `400` or `404`) do not count.

  Once exhausted, the guard returns `429 throttled` with `Retry-After`.
  Once tripped, the guard covers every authenticated Case resource route,
  including `GET /v2/usage/` and `GET /v2/info/`.

  A temporarily unreachable credential store instead returns
  `503 service_unavailable` with `Retry-After`. Follow the indicated delay and
  retry commands with the same `Idempotency-Key`.
</Accordion>

## Resource limits

A resource limit applies to the complete record, even when you build it over
several requests. A **per-command** limit applies only to the data sent together
in one request. These limits are independent of the rate limits above.

### Orders and claims

An [order](/api-docs/case-management-api/concepts/orders) groups the
[claims](/api-docs/case-management-api/concepts/claims) you want paywise to
collect from a debtor. These limits apply to invoice, rental, and titled orders
where the field is available.

| Business information | Maximum | Applies to |
| - | - | - |
| [Claims in an order](/api-docs/case-management-api/reference/orders/create-order#body-claims) | 50 | The complete order, including claims added later. |
| [Additional debtors jointly liable for an order](/api-docs/case-management-api/reference/orders/create-order#body-additional-debtor-ids) | 10 | `additional_debtor_ids`, in addition to the primary `debtor_id`. |
| [Invoice or contract lines supporting a claim](/api-docs/case-management-api/reference/claims/create-claim#body-one-of-0-items) | 100 | `items` on each receivable claim. |
| [Incidental charges, such as reminder fees](/api-docs/case-management-api/reference/claims/create-claim#body-one-of-0-additional-charges) | 50 | `additional_charges` on each receivable claim. |
| [Previous payment reminders](/api-docs/case-management-api/reference/claims/create-claim#body-one-of-0-reminders) | 50 | `reminders` on each receivable claim. |
| [Payments already received](/api-docs/case-management-api/concepts/payments) supplied when creating a claim | 50 | The inline `payments` array on each new claim; later payment reports use the payment endpoints. |
| [Description of the goods, services, or obligation](/api-docs/case-management-api/reference/claims/create-claim#body-one-of-0-subject-matter) | 2,000 characters | `subject_matter` on each claim. |
| [Explanation of the claim's legal basis](/api-docs/case-management-api/reference/claims/create-claim#body-one-of-0-legal-basis) | 2,000 characters | `legal_basis.description` on a receivable claim. |
| Explanation for withdrawing an order | 5,000 characters | `reason` on the [withdrawal command](/api-docs/case-management-api/reference/orders/withdraw-order). |

**Enforcement:** oversized arrays and text return `400 validation_error`.
Adding a claim to an order that already has 50 claims also returns `400`;
sending claims one at a time does not bypass the limit. The API rejects the
command instead of keeping only the first entries or shortening your text.
When a PATCH replaces a collection, the replacement must fit the same limit.

#### Unfinished drafts

An API-created draft expires after **90 days without a change**. The order's
`expires_at` field gives the deadline. A draft mutation refreshes it; reads
and PATCH requests that leave the stored values unchanged do not.

After the deadline, the order is shown as `expired` and accepts no further
change: every write and `finalize` answer `409 order_expired`, and nothing
refreshes the deadline. The daily cleanup deletes the draft and its owned
data, preserves reusable debtor records, and emits `order.expired`; subsequent
reads return `404`. Finalized orders and portal-created orders do not have
this expiry. See the [order lifecycle](/api-docs/case-management-api/concepts/orders#draft-and-finalization).

### Debtor information

A [debtor](/api-docs/case-management-api/concepts/debtors) is a reusable
record. The following limits apply both when you create one inside an order
and when you use the debtor endpoints directly.

| Information per debtor | Maximum | Field |
| - | - | - |
| Postal addresses | 5 | [`addresses`](/api-docs/case-management-api/reference/debtors/create-debtor#body-addresses) |
| Email addresses and telephone numbers, combined | 10 | [`communication_channels`](/api-docs/case-management-api/reference/debtors/create-debtor#body-communication-channels) |
| Bank accounts | 10 | [`bank_accounts`](/api-docs/case-management-api/reference/debtors/create-debtor#body-bank-accounts) |
| Legal representatives | 10 | [`legal_representatives`](/api-docs/case-management-api/reference/debtors/create-debtor#body-legal-representatives) |
| Representatives of a legal representative | 10 per representative | Nested `legal_representatives`; at most two representative levels. |

**Enforcement:** an oversized collection returns `400 validation_error`.
On updates, supplied arrays replace their collection, so the limit applies to
the full replacement, including retained entries. Omission preserves a
collection; `[]` clears it where allowed. Other requirements, such as a single
primary address, still apply.

### Documents and attachments

[Case documents](/api-docs/case-management-api/concepts/documents-and-communication)
provide evidence for claims, rental agreements, and enforceable titles, or
accompany messages and answers to client requests.

| Limit | Maximum | Meaning |
| - | - | - |
| Documents submitted together | 20 per command | Count all documents in the request, including those nested under different claims, titles, or a rental agreement. |
| Size of an individual document | 10 MiB (10,485,760 bytes) | Measured on the file bytes after base64 decoding, or on the multipart file. |
| Combined inline document content | 50 MiB per command | Sum of decoded file sizes across all nested documents, before base64 encoding. |
| Pages in an uploaded PDF | 100 | Applies to each PDF, independently of its file size. |

For example, six 9 MiB files each fit the individual file limit, but their
combined 54 MiB exceeds the inline command limit. Send fewer files per command
through the parent resource's document endpoint. The 20-document limit is a
submission limit, not a lifetime allowance for an order.

**Enforcement:** the Case Management API validates document counts, decoded
sizes, and PDF pages before accepting the command; the count is checked before
any file is decoded. Violations return `400`; file errors name `file` or
`base64`, including a nested document path for inline uploads. A PDF above 100
pages uses `page_limit_exceeded`. Correct the files or split the batch before
retrying. The bytes are stored during the request: if document storage is
briefly unavailable, the command answers `503 service_unavailable` with
`Retry-After`, creates nothing, and releases its `Idempotency-Key`, so retry it
with the same key. Accepted documents still undergo asynchronous scanning and
processing; check `status` and `failure_reason` before relying on their
availability.

[Mahnservice invoices](/api-docs/mahnservice-api/concepts/documents) accept
**one PDF per invoice**, with the same 10 MiB file and 100-page PDF ceilings.
Uploading again replaces the current PDF while the invoice is held. Oversized,
encrypted, corrupt, or non-PDF files and PDFs above 100 pages are rejected
during upload with the same `400` codes as the Case Management API (`encrypted`,
`page_limit_exceeded`, `corrupt`, `unsupported`); a storage fault during the
upload is `503 service_unavailable`; processing failures appear as
`status: failed`. An attached document must reach `ready` before the invoice
can be released.

### Companies and memberships

The [Partner API](/api-docs/partner-api/concepts/resources-and-memberships)
lets you onboard companies and invite their users.

| Information submitted for a company | Maximum | Field |
| - | - | - |
| Company notification recipients | 10 | [`notification_channels`](/api-docs/partner-api/reference/companies/onboard-a-company#body-notification-channels) |
| Company legal representatives | 3 | [`legal_representatives`](/api-docs/partner-api/reference/companies/onboard-a-company#body-legal-representatives) |
| Users invited during company creation | 10 | [`users`](/api-docs/partner-api/reference/companies/onboard-a-company#body-users); manage later invitations through the membership endpoints. |

**Enforcement:** oversized lists return `400 validation_error`. Notification
recipient and legal representative limits also apply to replacement lists
on updates. The initial `users` limit applies to company creation, not to the
company's total number of memberships.

### Webhook subscriptions

You can register **20 [webhook endpoints](/api-docs/essentials/webhooks) per
company** in the Case Management API, or **20 per Partner** in the Partner API. Enabled
and disabled endpoints both count.

**Enforcement:** creating a 21st endpoint returns `409 webhook_limit_reached`.
Delete an endpoint you no longer need before creating another; disabling it
does not free capacity. The separate [webhook delivery rate limit](#api-rate-limits)
controls how often you can test or manually redeliver a webhook.

## Request size and pagination

These technical safeguards apply across all three APIs.

| Request property | Limit | Enforcement |
| - | - | - |
| Results per page | `limit` defaults to 10; accepted range 1–100 | Invalid integers (ASCII digits only) or out-of-range values return `400 validation_error`, with `invalid_parameter` on the query parameter. Values above 100 are rejected, not capped. |
| Starting position in a result list | `offset` must be an integer of 0 or greater | Invalid values return the same query-parameter error. |
| Declared request body size | `Content-Length` at most 72 MiB | Larger requests return `413 request_too_large` before the body is read and consume no quota. A chunked body without `Content-Length` returns `411 length_required`. |
| Request charset | UTF-8 (UTF-16 and UTF-32 are accepted) | Any other `Content-Type` charset returns `415 unsupported_media_type`. |
| JSON nesting | At most 64 levels | Deeper JSON returns `400 parse_error`. Non-finite numbers, unpaired surrogate escapes, and duplicate object members are also rejected. |

Base64 encoding increases the transmitted size: 50 MiB of decoded documents
becomes about 67 MiB before the surrounding JSON. Both the decoded-document
limit and request-body limit must be respected. Use
[pagination](/api-docs/essentials/pagination-and-synchronization) to work through
larger result sets.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.