Kua uses conventional HTTP status codes and a consistent JSON error body.
Error shape
code — a stable, machine-readable identifier you can branch on.message — a human-readable explanation (may change; don’t parse it).
Status codes
| Status | Meaning |
|---|
200 / 201 / 202 | Success. |
204 | Success, no content. |
400 | Malformed request or a validation error (see code). |
401 | Missing or invalid API key. |
403 | The key is valid but lacks the required scope (INSUFFICIENT_SCOPE). |
404 | The resource doesn’t exist (or isn’t yours). |
409 | Conflict — e.g. an Idempotency-Key reused with a different body. |
5xx | Something went wrong on Kua’s side. Safe to retry with the same idempotency key. |
Common codes
| Code | When |
|---|
INSUFFICIENT_SCOPE | The API key is missing a required scope. |
MODULE_NOT_ENABLED | The endpoint belongs to an add-on the company hasn’t enabled. The body includes the module; a company admin enables it in Settings → Modules. |
TEST_MODE_UNSUPPORTED | A write to an add-on endpoint was attempted with a kua_test_ key. Add-ons have no sandbox yet — use a live key. |
WEBHOOK_INVALID_URL | A webhook endpoint URL wasn’t a valid absolute URL. |
Every request is scoped to the company that owns the API key. Asking for another
company’s data returns 404, never that data.