Errors

Every Nudj API endpoint uses the same error envelope — the tRPC wire format — so clients can share a single error handler across all three APIs.

Envelope

{
  "message": "Human-readable description of the problem.",
  "code": "TRPC_ERROR_CODE",
  "data": {
    "httpStatus": 400,
    "path": "endpointName"
  }
}

Field	Description
`message`	Free-text description. Safe to surface in developer-facing logs. Don’t surface verbatim to end users — messages aren’t localised.
`code`	Stable tRPC error code — e.g. `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BAD_REQUEST`, `INTERNAL_SERVER_ERROR`.
`data.httpStatus`	The HTTP status code of the response. Mirrors the response status line.
`data.path`	Name of the endpoint procedure that rejected the request. Useful for log correlation.

Common status codes

400 — `BAD_REQUEST`

Zod validation failure on the request body, a path/query parameter, or a required header.

{
  "message": "Invalid input: expected string for body.communityId",
  "code": "BAD_REQUEST",
  "data": { "httpStatus": 400, "path": "createChallenge" }
}

Fix: read the message — it names the offending field. Re-check your request shape against the endpoint’s schema.

401 — `UNAUTHORIZED`

Token missing, malformed, expired, or issued for a different organisation’s subdomain.

{
  "message": "You must be logged in to access this endpoint.",
  "code": "UNAUTHORIZED",
  "data": { "httpStatus": 401, "path": "getAchievements" }
}

Fix: see Authentication troubleshooting.

403 — `FORBIDDEN`

Token is valid but lacks the RBAC permissions for the requested action. Most common on Admin endpoints.

{
  "message": "Insufficient permissions for this operation.",
  "code": "FORBIDDEN",
  "data": { "httpStatus": 403, "path": "deleteChallenge" }
}

Fix: raise the token’s role (if appropriate), or narrow the request to a community the token has access to.

404 — `NOT_FOUND`

No entity matches the request — wrong id, wrong organisation, or the entity has been deleted.

{
  "message": "Challenge not found.",
  "code": "NOT_FOUND",
  "data": { "httpStatus": 404, "path": "getChallengeById" }
}

409 — `CONFLICT`

The request would break a uniqueness constraint or violates current state (e.g. trying to claim a reward already claimed, re-use a one-time code, or register a duplicate domain).

{
  "message": "Reward already claimed.",
  "code": "CONFLICT",
  "data": { "httpStatus": 409, "path": "claimReward" }
}

500 — `INTERNAL_SERVER_ERROR`

An unexpected runtime error. The response body surfaces the tRPC code but the detailed stack trace is logged server-side and not returned.

{
  "message": "An unexpected error occurred.",
  "code": "INTERNAL_SERVER_ERROR",
  "data": { "httpStatus": 500, "path": "getMyProfile" }
}

Response-validation errors can also surface as 500. If the API returns data that fails its own output schema (historically this has happened on a few integration endpoints when new enum values are rolled out), clients receive a generic 500 rather than a typed failure. If you consistently hit a 500 on a previously-working endpoint, file a bug — it’s very likely a schema regression rather than a runtime fault.

Client handling pattern

async function nudjRequest(path, init = {}) {
  const response = await fetch(`https://${DOMAIN}${path}`, {
    ...init,
    headers: {
      'Authorization': `Bearer ${process.env.NUDJ_API_TOKEN}`,
      'Content-Type': 'application/json',
      ...(init.headers ?? {}),
    },
  });

  if (!response.ok) {
    const error = await response.json().catch(() => null);
    // error has shape { message, code, data: { httpStatus, path } }
    throw Object.assign(
      new Error(error?.message ?? `HTTP ${response.status}`),
      { code: error?.code, httpStatus: response.status, path: error?.data?.path },
    );
  }

  return response.json();
}

import os, requests

def nudj_request(path, **kwargs):
    response = requests.request(
        url=f"https://{DOMAIN}{path}",
        headers={
            "Authorization": f"Bearer {os.environ['NUDJ_API_TOKEN']}",
            "Content-Type": "application/json",
            **kwargs.pop("headers", {}),
        },
        **kwargs,
    )
    if not response.ok:
        try:
            error = response.json()
        except ValueError:
            error = {}
        raise RuntimeError(
            f"Nudj API error: {error.get('code', response.status_code)} — {error.get('message')}"
        )
    return response.json()

Retries

The APIs don’t emit Retry-After headers, but 5xx responses (500, 502, 503) are always safe to retry with exponential backoff. Do not blindly retry 4xx — those are request-shape errors and will fail identically a second time.

Authentication

401 and 403 scenarios in depth.

Pagination

Common 400 errors on list endpoints.

API Reference

Authentication & User Linking

Webhooks

MCP Server

Resources

Envelope

Common status codes

400 — `BAD_REQUEST`

401 — `UNAUTHORIZED`

403 — `FORBIDDEN`

404 — `NOT_FOUND`

409 — `CONFLICT`

500 — `INTERNAL_SERVER_ERROR`

Client handling pattern

Retries

Authentication

Pagination

​Envelope

​Common status codes

​400 — BAD_REQUEST

​401 — UNAUTHORIZED

​403 — FORBIDDEN

​404 — NOT_FOUND

​409 — CONFLICT

​500 — INTERNAL_SERVER_ERROR

​Client handling pattern

​Retries

​Related

Authentication

Pagination

Envelope

Common status codes

400 — `BAD_REQUEST`

401 — `UNAUTHORIZED`

403 — `FORBIDDEN`

404 — `NOT_FOUND`

409 — `CONFLICT`

500 — `INTERNAL_SERVER_ERROR`

Client handling pattern

Retries

Related