Operate

Errors and rate limits

Handle Problem Details responses, correlation IDs, and request limits.

Problem details

Errors use application/problem+json (RFC 7807). Correlation is available through the optional X-Correlation-Id request header, the response header, and the correlationId response field.

Example

json

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key is missing or invalid",
  "instance": "/api/v1/payment-sessions",
  "code": "api-key.invalid",
  "correlationId": "c7ccb49d-e6bb-45f7-b834-93c4521a6857"
}

Common error codes

API key errors

Name	Type	Description
`api-key.invalid`	401	Missing, malformed, or unrecognized API key.
`api-key.revoked`	401	API key has been revoked.
`api-key.expired`	401	API key has passed its expiry.

Business account errors

Name	Type	Description
`business.compliance-not-approved`	403	KYB not approved. Complete business verification in the portal.
`business.not-active`	403	Business suspended or inactive. Contact Zippy Pay support.
`business.payment-id-not-configured`	403	No active receive payment ID. Create one under business settings before session create.

Payment session errors (merchant server)

Name	Type	Description
`payment-session.not-found`	404	Unknown sessionId or merchantReference for your business.
`payment-session.id-invalid`	400	sessionId is not UUID v4.
`payment-session.redirect-url-invalid`	400	successUrl or failureUrl must use HTTPS and match a registered allowed checkout origin or your registered business website. Credentials in URLs are not allowed.
`payment-session.metadata-too-large`	400	metadata exceeds the 4096 UTF-8 byte limit.
`payment-session.reference-conflict`	409	merchantReference is already in use for another session.
`IDEMPOTENCY_CONFLICT`	409	Idempotency-Key was reused incompatibly.
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded; inspect Retry-After.

Checkout SDK errors (browser)

Name	Type	Description
`payment-session.origin-not-allowed`	403	Page origin is not registered. Add the domain under Integrations → Allowed browser origins in the portal.

Origin allowlisting applies to embedded checkout in the browser. Server-side session create is authenticated with your API key — never send zp_live_ from client code. Other Checkout SDK error codes are listed in Checkout SDK error handling.

Portal origin registration errors

Name	Type	Description
`business.allowed-origin-invalid`	400	Bad origin format, or localhost registered in production/staging.
`business.allowed-origin-duplicate`	409	Origin already registered for this business.
`business.allowed-origin-limit`	400	Maximum of 10 allowed origins reached.

Rate limits

Name	Type	Description
`POST /api/v1/payment-sessions`	120 / 60s	Per API key.
`GET /api/v1/payment-sessions?merchantReference=`	120 / 60s	Per API key.
`GET /api/v1/payment-sessions/{sessionId}`	120 / 60s	Per API key or client IP (composite route).

Exceeding the limit returns HTTP 429 and a Retry-After response header.
Wait for the indicated duration before retrying; use exponential backoff and jitter for concurrent workers.
Poll merchant GET endpoints from your backend only — never with an API key in browser code.

Webhook deliveries

Dashboard guide