Errors & Conventions
Every PosNova endpoint follows the same rules for authentication, pagination, success envelopes and error reporting — learn them once, use them everywhere.
The response envelope
Successful responses wrap the payload in data. List endpoints add a pagination object. Error responses always carry an error string you can log or show.
// Success (list)
{ "success": true, "data": [ … ], "pagination": { "total": 231, "page": 1, "limit": 50 } }
// Success (single resource)
{ "success": true, "data": { … } }
// Error
{ "success": false, "error": "customer.name is required" }
// Auth error (from the key middleware)
{ "error": "Missing or invalid Authorization header" }HTTP status codes
| Status | Description |
|---|---|
200 OK success • optional | The request succeeded; the payload is in data. |
201 Created success • optional | Resource created — currently returned by POST /v1/orders. |
400 Bad Request client error • optional | Malformed JSON, a missing required field, or invalid items (unknown product, inactive product, bad quantity). |
401 Unauthorized client error • optional | Missing Authorization header, wrong key format (must start with pn_live_ or pn_test_), or a key that does not exist. |
403 Forbidden client error • optional | The key is valid but deactivated or expired, or the owning store is inactive. |
404 Not Found client error • optional | The resource does not exist in your store — also returned for IDs that belong to another store. |
422 Unprocessable client error • optional | Input was well-formed but the order engine rejected it (e.g. out-of-stock at commit time). |
500 Server Error server error • optional | Something failed on our side. Retry with backoff; the response never leaks internals. |
Pagination
| Parameter | Description |
|---|---|
limit integer • optional | Page size. Default 50, minimum 1, maximum 100 — values outside the range are clamped, never rejected. |
page integer • optional | 1-based page number. Default 1. |
The response echoes total (all matching rows), page and limit — the last page is Math.ceil(total / limit).
Test vs live keys
Keys prefixed pn_test_ behave identically to live keys but mark requests as test traffic, so you can develop and run CI without polluting production analytics. Both key types are scoped to a single store and are revocable instantly from Settings → Developer API.
Be a good API citizen
Per-key rate limiting is on the public roadmap; until then requests are subject to fair-use monitoring. Cache reads where you can, use webhooks-style polling intervals of 30s+ for order lists, and always handle 5xx with exponential backoff — your key can be throttled if a runaway loop hammers the API.
Status: Operational