Errors

For Developers

All KynectLocal API errors return a consistent JSON envelope so you can handle failures predictably regardless of which endpoint triggered them.

When you’d use this

• Writing error-handling logic for your integration
• Debugging an unexpected response code
• Understanding why a feature-gated endpoint returned 403

---

Standard error envelope

Every error response body follows this shape:

{
  "error": "error_code",
  "status": 400
}

Both error (a machine-readable string) and status (the HTTP status code repeated in the body) are always present.

---

Feature entitlement errors

When a request touches a feature the brand is not entitled to use, the API returns a 403 with an expanded error shape:

{
  "error": "feature_not_entitled",
  "status": 403,
  "feature": "api_access",
  "isTrial": false,
  "upgradeRequired": true,
  "requiredTier": "authority"
}

Field	Type	Description
error	string	Always "feature_not_entitled" for this error type
status	number	Always 403
feature	string	The specific feature the brand lacks access to
isTrial	boolean	true if the brand has a trial for this feature that has expired
upgradeRequired	boolean	true if upgrading the plan tier would grant access
requiredTier	string	The minimum plan tier required: "local", "network", or "authority"

💡 Tip

Use upgradeRequired and requiredTier to show the brand admin a targeted upgrade prompt in your integration rather than a generic error message.

---

Common error codes

HTTP status	error value	Meaning
400	bad_request	The request body or query parameters are malformed
401	unauthorized	Missing, invalid, expired, or revoked X-API-Key header
403	forbidden	Valid key but insufficient access to this resource
403	feature_not_entitled	The brand does not have an entitlement for this feature
404	not_found	The requested resource does not exist
429	rate_limit_exceeded	Too many requests — check Retry-After header
500	internal_error	Unexpected server error — retry with exponential backoff

---

Authentication errors (401)

A 401 is returned whenever the API cannot authenticate the request. All of the following cause a 401:

• No X-API-Key header sent
• Key does not exist or was never valid
• Key has been revoked (immediately after revocation — no grace period)
• Key has passed its expiry date

{
  "error": "unauthorized",
  "status": 401
}

There is no distinction in the response body between a missing key and a revoked one — this is intentional to avoid leaking information to attackers. If you are seeing unexpected 401 responses, check the Audit Log for the key in Integrations → API Keys to see the last authentication events.

---

Rate limit errors (429)

When a per-key rate limit is exceeded, the response includes a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714000060

{
  "error": "rate_limit_exceeded",
  "status": 429
}

Always respect Retry-After. See Rate Limits for the full per-key limit table and retry patterns.

---

Handling errors in code

A minimal error handler in JavaScript:

const res = await fetch('https://api.kynectlocal.com/v1/locations', {
  headers: { 'X-API-Key': process.env.KYNECT_API_KEY }
});

if (!res.ok) {
  const err = await res.json();

  if (err.error === 'feature_not_entitled') {
    console.error(`Feature "${err.feature}" requires the ${err.requiredTier} plan.`);
  } else {
    console.error(`API error ${err.status}: ${err.error}`);
  }
}

---

Related

• Rate Limits — 429 responses and retry handling
• Authentication — 401 and 403 responses from bad keys
• Code Samples — full working examples with error handling