# Payclave API policy

- [OpenAPI 3.1 specification](/openapi.json)
- [Complete HTTP reference](/developers/docs#api-reference)
- [Agent index](/llms.txt)

## Versioning and deprecation

The API base URL is `https://api.payclave.com`. Major versions are explicit in the URL (`/v1/`). Breaking request or response changes require a new major path. Optional response fields and new error codes may be added within a version: ignore unknown fields and fall back to the HTTP status for unknown error codes.

No v1 retirement is scheduled. Before retiring an operation, publish a migration guide and explicit retirement date here, mark it `deprecated: true` in OpenAPI, and return `Deprecation` and `Sunset` headers on affected API responses. `Deprecation` uses an RFC 9745 Structured Field date (`@` followed by Unix seconds). `Sunset` uses an RFC 8594 HTTP date and must not precede deprecation. No minimum notice interval is currently committed.

## Errors

Errors retain Payclave's JSON envelope, rather than application/problem+json:

```json
{"success":false,"error":{"code":"VALIDATION_ERROR","message":"Invalid request."},"meta":{"requestId":"req_example"}}
```

`error.details` is optional JSON context. Use `error.code` for decisions and retain `meta.requestId` or `X-Request-Id` for support. Do not retry validation or authentication failures without correcting the request. Only retry mutations with supported idempotency protection; webhook endpoint creation and synthetic test delivery do not support idempotent replay.

## Rate limits

Responses passing an enforced quota include the Structured Field lists from `draft-ietf-httpapi-ratelimit-headers-11` (an IETF Internet-Draft, not yet an RFC):

```http
RateLimit-Policy: "quota-1";q=20;w=60
RateLimit: "quota-1";r=19;t=30
```

`q` is the request allowance per `w` seconds. `r` is remaining requests after reserving this request; `t` is seconds until reset. Multiple policies can apply, with response-local names. Successful authentication can refund a reservation after the response. Values are snapshots and concurrent requests can consume them. Quota responses are private and must not be cached.

A quota rejection returns HTTP 429 with `Retry-After` in seconds. Wait at least that long; otherwise slow down before remaining quota reaches zero. Headers are omitted if no quota was applied: their absence does not promise unlimited capacity. The existing limits are unchanged. Publishable checkout creation is limited to 20 requests/minute per key and client IP; other public checkout and authentication routes have their own quotas. Secret-key routes do not advertise a fabricated quota.

## Markdown representations

The home page, developer documentation and technical guides support `Accept: text/markdown`, including quality values. Both HTML and Markdown variants vary on `Accept`; unsupported document media types return 406. Unknown public paths return HTTP 404 with recovery links for Markdown clients. Application pages, authentication, checkout and API JSON responses retain their existing handlers.