Errors
The API uses standard HTTP status codes. A 2xx is success; a 4xx means the
request was rejected and the body says why.
Response shapes
Most endpoints return a small JSON error body:
{ "error": "resource not owned by this key" }The plan gate adds an upgrade flag so a client can tell "you're not allowed"
apart from "your plan doesn't include this":
{ "error": "api access not in plan", "upgrade": true }POST /_naulon/verify, the settlement endpoint, carries an explicit ok field
on every response so you can branch without checking the status code:
{ "ok": false, "error": "resource not owned by this key" }Status codes
| Code | Meaning |
|---|---|
200 |
Success. For verify, the body is the receipt (ok: true, settlementRef, licenseJws). |
204 |
GET /_naulon/quote only: no toll, the resource is free to read. There's no body. |
400 |
The request was malformed: a missing parameter, an invalid resource URL, or a body that didn't parse. |
401 |
Missing or unrecognized key. |
402 |
POST /_naulon/verify only: the payment couldn't be settled (bad signature, expired quote). The error says which. |
403 |
The key isn't allowed: it's bound to a different site, the site is suspended, or the site's plan doesn't include API access (upgrade: true). |
Authentication is checked before the request body, so an unauthenticated call
always gets 401, never a 400 about the body it also happened to get wrong.
Example
curl -i https://gate.naulon.app/_naulon/tenants/self
# HTTP/1.1 401 Unauthorized
# {"error":"unauthorized"}