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

# Request limits

> Request body size, string field length, and metadata limits for the PayNext public API and SDK payments endpoints.

Public API write requests and SDK payment requests enforce body size and field length limits. Length limits count Unicode characters (runes), not bytes. Body size and metadata serialized size count bytes.

## Request body size

Write requests (`POST`, `PUT`, `PATCH`, `DELETE`) accept a body of at most **256 KiB** (262144 bytes) on:

* Every public API endpoint, including client sessions, customers, payments, refunds, and subscriptions.
* Every `/sdk/payments` endpoint, including `create`, `create/billing/agreement`, the `setup-intent` and `payment-intent` endpoints, and `apple-pay/validate-merchant`.

`GET` requests have no body limit. All other endpoints keep the global limit of 5 MiB.

A larger body returns **HTTP 413** with a short JSON body. The submitted content is never echoed in the response.

```json title="413 response" theme={"system"}
{
  "error": {
    "message": "Request Entity Too Large"
  }
}
```

## String field limits

| Field | Limit | Unit |
| :- | -: | :- |
| `customer.full_name` / `full_name` | 255 | characters (runes) |
| `customer.email` / `email` (customer and SDK create) | 254 | characters (runes) |
| `payment_method.details.email` / SDK `card.email` | 254 | characters (runes) |
| `external_id` | 255 | characters (runes) |
| `phone` (customer PATCH, payment method, SDK) | 32 | characters (runes) |
| `address.line1` / `billing_address.line1` / `payment_method.billing_address.line1` | 255 | characters (runes) |
| `address.line2` / `billing_address.line2` / `payment_method.billing_address.line2` | 255 | characters (runes) |
| `address.city` / `billing_address.city` / `payment_method.billing_address.city` | 100 | characters (runes) |
| `address.state` / `billing_address.state` / `payment_method.billing_address.state` | 100 | characters (runes) |
| `address.postal_code` / `billing_address.postal_code` / `payment_method.billing_address.postal_code` | 32 | characters (runes) |
| Payment method `name` | 255 | characters (runes) |
| Payment method `phone` | 32 | characters (runes) |
| PayPal `payer_info.email` | 254 | characters (runes) |
| PayPal `payer_info.first_name` | 100 | characters (runes) |
| PayPal `payer_info.last_name` | 100 | characters (runes) |
| PayPal `payer_info.payer_id` | 64 | characters (runes) |
| PayPal `payer_info.tenant` | 64 | characters (runes) |
| PayPal `billing_agreement_id` | 128 | characters (runes) |
| SDK `paypal.billing_agreement_token` | 128 | characters (runes) |
| `additional_fields[].value` | 4096 | characters (runes) |
| `national_document_id` | 64 | characters (runes) |
| `cit_network_transaction_id` | 128 | characters (runes) |
| SDK / APM `client_session` | 128 | characters (runes) |
| SDK `three_ds_session_id` | 128 | characters (runes) |
| SDK `payment_method.id` | 128 | characters (runes) |
| SDK `venmo.device_data` | 4096 | characters (runes) |
| SDK `venmo` `nonce` / `type` | 256 | characters (runes) |
| SDK `return_url` (Amazon setup-intent) | 2048 | characters (runes) |
| Apple validate-merchant `session_id` | 128 | characters (runes) |
| Apple validate-merchant `validation_url` | 2048 | characters (runes) |
| Apple validate-merchant `initiative_context` | 255 | characters (runes) |
| Apple validate-merchant `display_name` | 255 | characters (runes) |
| `apple_pay_direct.card_network` / `google_pay_direct.card_network` | 32 | characters (runes) |
| `apple_pay_direct.card_details` / `google_pay_direct.card_details` | 128 | characters (runes) |

## Metadata limits

| Rule | Limit | Unit |
| :- | -: | :- |
| Key length | 64 | characters (runes) |
| String value length | 4096 | characters (runes) |
| Key count | 100 | keys |
| Serialized size | 16384 | bytes |
| Nesting depth | 5 | levels |

Metadata values can be any JSON type (string, number, boolean, null, array, or object). Only string values are limited by length. Every value counts toward the serialized size.

### Merged metadata

When a write merges new metadata into stored metadata, PayNext checks the merged result against these limits. A request whose merged metadata exceeds a limit returns **HTTP 400**. This applies to `PATCH /customers/{id}`, `PATCH /subscriptions`, and `POST /payments/refund/{id}` with `metadata`.

If stored metadata is already over a limit, you can still update it as long as the update doesn't grow that dimension. Deleting keys is always allowed.

Client sessions validate each metadata object against the absolute limits above.

## Error format

Validation failures return **HTTP 400** with this body:

```json title="400 response" theme={"system"}
{
  "error": {
    "message": "Invalid request body",
    "validation_errors": [
      {
        "field": "customer.full_name",
        "message": "must be at most 255 characters"
      }
    ]
  }
}
```

The message format depends on the field.

| Fields | `field` | `message` |
| :- | :- | :- |
| `full_name`, `email`, `external_id`, and `name` on customer endpoints and SDK create | JSON path | `must be at most N characters` |
| All other string fields in the table above | Property name, such as `Phone` | `<json.path>: max N characters` |
| Metadata | `Metadata` | `<path>: <reason>` |

The JSON path of the first group is relative to the endpoint. It has no `customer.` prefix on `PATCH /customers/{id}` and SDK create (`full_name`, `email`, `name`). It has the prefix on `POST /payments/card`, `POST /customers`, and client sessions (`customer.email`, `customer.external_id`). Use `payment_method.name` on `POST /customers`.

For the second group, an oversized `phone` returns `phone: max 32 characters` and an oversized `additional_fields[0].value` returns `additional_fields[0].value: max 4096 characters`.

For metadata, `<path>` is `metadata`, `customer.metadata`, `subscription.metadata`, or `payment.metadata`. `<reason>` is one of `too many keys`, `key length exceeds limit`, `value length exceeds limit`, `nesting exceeds limit`, or `serialized size exceeds limit`.

Other errors:

* Invalid enum values return `<json.path>: invalid value`.
* Malformed JSON returns `invalid request body`.

Error messages never contain the submitted value.


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