Idempotency, errors & rate limits

Idempotency

Any write (POST, PUT, PATCH, DELETE) accepts an Idempotency-Key header. If you retry with the same key, Bizzle replays the original response instead of executing the request again.

Idempotency-Key: order-1042

• Keys are namespaced per merchant and expire after 24 hours.
• Only responses with status < 500 are cached — 5xx errors are not cached, so a retry after a server error will re-execute.
• GET requests ignore the header.

Tip

Generate the key from the event that caused the request (e.g. your order ID), not randomly. That is what makes retries safe.

Request IDs

Every /v1 response carries an X-Request-Id (req_…). Include it in support requests and pair it with GET /v1/logs to inspect the request.

Rate limits

Limits are applied per merchant (falling back to client IP), with a fixed 60-second window:

Requests	Limit
Reads (GET/HEAD/OPTIONS)	100 / min
Writes	60 / min

Every response includes:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1760000000

When the limit is exceeded you get 429 with a Retry-After header (seconds):

{ "error": "rate_limited", "message": "…", "code": "rate_limit_exceeded" }

Errors

Errors return a JSON body with a message and an HTTP status. 5xx responses are generic (Internal Server Error) and never leak internals — use the X-Request-Id to correlate with logs.

Status	Meaning
400	Malformed request
401	Missing or invalid key
403	Publishable key used where a secret key is required
404	Resource not found (or not owned by your merchant)
429	Rate limit exceeded — retry after Retry-After
5xx	Server error — retry with the same Idempotency-Key