Documentation · API

Error reference

Every NessyAPI error response carries a stable error.code field. This page lists every code we currently emit with the HTTP status, what causes it, and how to recover. Linkable per-code via #<code> anchor — the dashboard's auth pages link straight here when an error appears.

validation_error HTTP 422

Your request body was syntactically valid JSON but failed schema or business-rule checks. The response includes a detail.field_errors array pointing at the offending fields.

What to do: Inspect detail.field_errors. Common causes: missing required field, wrong type, invalid email format, password below complexity requirements, or a value outside an allowed enum.

rate_limited HTTP 429

You exceeded a per-IP or per-account request budget. Auth endpoints (register, login, forgot-password) are limited to a small number of attempts per hour to deter brute-force.

What to do: Wait the duration shown in the message (typically 60 minutes for register / login, 15 for verify-email). The Retry-After response header (when present) carries the exact wait in seconds. Repeated 429s from a stable IP can be raised by support.

unauthorized HTTP 401

No valid credential was presented. For dashboard pages this means the session cookie is missing, expired, or signed by an old key. For SDK calls it means the Authorization: Bearer nsy_... header is missing or invalid.

What to do: Sign in again. SDK clients should rotate the API key from the dashboard. If your session works in some endpoints but not others, your cookie may have been revoked — sign out everywhere and back in.

forbidden HTTP 403

You authenticated successfully but lack the scope or role for this action. Examples: a viewer role calling POST /v1/admin/team/invite, or an Origin-cookie request from a domain not in the CORS allowlist.

What to do: Ask your workspace owner to grant you a role with the required scope (admin or owner for team management; developer or above for sessions:write). For Origin failures, verify the dashboard host is in the backend's CORS allowlist.

not_found HTTP 404

The resource (session, API key, webhook subscription, …) does not exist or was already deleted. Some endpoints return 404 instead of 403 to avoid leaking existence to unauthorized callers.

What to do: Double-check the ID in the URL. If the resource was deleted, recreate it from the dashboard. For session IDs, sessions older than the retention window (30 days) are pruned automatically.

method_not_allowed HTTP 405

The endpoint exists but does not accept the HTTP verb you used. For example, GET /v1/auth/register returns 405 because register is POST-only.

What to do: Re-read the endpoint reference and use the documented method. If your form is silently sending GET, ensure your JS handler calls e.preventDefault() before delegating to fetch.

conflict HTTP 409

The state you're trying to create already exists. Inviting an email that's already a member, accepting an invite into a tenant where the email is already registered, etc.

What to do: If you're inviting a colleague who's already in the workspace, no action is needed. If you're accepting an invite and it says the email is already registered in this tenant, sign in instead of accepting.

payment_required HTTP 402

Your token balance is depleted and the endpoint you called is billable. The platform refuses to debit you into a negative balance unless overage_allowed is set on your tenant.

What to do: Top up your balance from the Billing page in the dashboard. Webhook deliveries and read-only endpoints continue to work even when the balance is zero — only billable session/NLP routes return 402.

bad_request HTTP 400

Your request was malformed at a level lower than schema validation. Bad JSON syntax, oversized header, contradictory query parameters, or a required header missing.

What to do: Inspect the response message for specifics. Most common cause is sending a Content-Type mismatch (e.g. application/x-www-form-urlencoded to a JSON-only endpoint).

request_timeout HTTP 408

The server gave up waiting for the request body. Typically your connection stalled mid-upload.

What to do: Retry. If it keeps happening, check for upload bandwidth issues on your side.

gone HTTP 410

The endpoint has been deprecated and removed past its sunset date. Older versions of the SDK or hand-rolled clients may still hit /v1/auth/invite after 2026-07-01, for example.

What to do: Migrate to the successor endpoint named in the response Link: <...>; rel="successor-version" header. Upgrade to the latest SDK version which routes to the right endpoints automatically.

payload_too_large HTTP 413

Your request body exceeded the platform limit (1 MB by default for most endpoints).

What to do: Shrink the payload. For sessions, this usually means you're sending an enormous raw_text — split it into smaller turns. The limit is configurable per-tier; enterprise contracts can raise it.

unsupported_media_type HTTP 415

You sent a Content-Type other than application/json to a JSON-only endpoint, or vice versa.

What to do: Set Content-Type: application/json on POST/PUT/PATCH requests carrying a JSON body.

request_too_large HTTP 413

Same condition as payload_too_large. Raised by the request-size middleware before route dispatch.

What to do: See payload_too_large.

internal_server_error HTTP 500

Something went wrong on our side that wasn't anticipated. The response carries a request_id we can correlate against logs.

What to do: Retry once. If it persists, send the request_id to support@healthyness.cz with a description of what you were doing.

not_implemented HTTP 501

The endpoint is documented but not yet wired up, or feature-flagged off for your tenant.

What to do: Check the changelog and roadmap. Contact support if you expected this to be live.

bad_gateway HTTP 502

An upstream dependency (Azure OpenAI, the engine container) returned an unexpected response.

What to do: Retry after a short delay. Persistent 502s are usually visible on the status page; check there before re-trying repeatedly.

service_unavailable HTTP 503

A critical dependency (Postgres, Redis) is currently unreachable, OR an authentication path is fail-closed because rate-limit storage is down. The platform refuses to serve traffic rather than degrade silently.

What to do: Wait 30-60 seconds and retry. The status page reflects ongoing incidents; if 503s last beyond five minutes, escalate to support.

gateway_timeout HTTP 504

An upstream call (typically the LLM extraction step) ran longer than the platform's per-request budget.

What to do: Retry. For sustained timeouts on POST /v1/sessions/.../answer, switch to the chunked variant or split the answer into smaller parts.

Source of truth for the code list lives in nessyapi.app._STATUS_CODE_MAP. Mismatches between this page and the backend are a bug — report to support@healthyness.cz.