Errors

Every API error uses one JSON envelope with a stable code and a readable message. The codes, their HTTP statuses, and what to do about each.

Errors from the public API are JSON with the same shape:

JSON

{ "ok": false, "error": { "code": "invalid_input", "message": "u is required and must be at most 2048 bytes" } }

Successful payment calls answer { "ok": true, "data": { ... } }; successful event calls answer 204 with no body. Branch on error.code, which is stable, and log error.message, which explains the cause in plain words and may be reworded.

Codes

Code	Status	Meaning	What to do
`invalid_input`	400	A field failed validation, or the JSON is malformed or has unknown fields	Fix the request; retrying it unchanged fails again
`invalid_input`	413	An events body is larger than 8 KB	Send fewer events per request
`unauthorized`	401	The key is missing, malformed, unknown or revoked	Check the `Authorization: Bearer mk_live_...` header
`forbidden`	403	The key lacks the endpoint's scope, or the event names another site	Use a key with the right scope for the right site
`not_found`	404	The site does not exist	Check the site id
`quota_exceeded`	429	The account has used its monthly events	Upgrade, or wait for `Retry-After` seconds (the start of the next UTC month)
`rate_limited`	503	The ingest queue is momentarily full	Retry after `Retry-After` seconds (2)
`internal`	500	Something failed on ProductLense's side	Retry with backoff; payments are idempotent by `payment_id`

The API also defines plan_required, provider_error and rate_limited with status 429 for other surfaces; the two public endpoints do not return them today.

Validation messages

Payment validation lists every bad field at once, sorted by field name:

Text

invalid payment input: amount: must be greater than 0; kind: must be one of charge, refund, chargeback

Events stop at the first bad event and name the rule it broke, for example e must be pageview, $identify or match ^[a-zA-Z0-9_\- ]{1,64}$ or hostname not allowed for this site. The full lists are on Events API and Payments API.

Retries

Retry 500 and 503 with exponential backoff and jitter, honouring Retry-After when present.
Do not retry 400, 401, 403 or 404 without changing the request.
Payments can be retried safely: the same payment_id updates instead of duplicating. Events have no idempotency key, so a retried event after a timeout may be counted twice.

Codes#

Validation messages#

Retries#

Codes

Validation messages

Retries