Errors & status codes

Response envelope

All responses — successful and failed — share the same shape:

{
  "success": true,
  "data": { ... },
  "message": "..."
}

{
  "success": false,
  "message": "Human-readable summary",
  "data": null,
  "error": "Optional detail or array of field errors"
}

Always check success, not just the HTTP status. message is safe to surface to end users; error is for logs and debugging.

Status codes at a glance

lehnz does not use 422. Validation failures return 400.

400 Bad Request

The request was structurally invalid — missing field, wrong type, schema mismatch. Validation errors include a per-field error array:

{
  "success": false,
  "message": "Validation Failed",
  "error": [
    { "path": "email", "message": "Invalid email" },
    { "path": "password", "message": "String must contain at least 8 character(s)" }
  ]
}

401 Unauthorized

The request was rejected because credentials are missing, invalid, or expired. Never retry a 401 with the same credentials — fetch new ones.

403 Forbidden

The credential is valid but does not have permission for this resource or action.

404 Not Found

The resource doesn't exist, or it exists in a different organization. lehnz does not leak existence — a 404 looks the same whether the ID is invalid or simply belongs to another tenant.

429 Too Many Requests

You hit a rate limit. The response includes RateLimit-* headers (draft-7) you can use to compute the right backoff.

See Retries & rate limits for backoff strategies and how to design around the limits.

500 Internal Server Error

An unexpected server-side failure. The response is generic — internal details are scrubbed before they reach the client.

{
  "success": false,
  "message": "An unexpected error occurred",
  "data": null,
  "error": null
}

500s are exceptional — retry once with a short delay, then escalate. If you see them in volume, contact support with timestamps and any unique request IDs from your client logs.

A defensive client

A complete client should branch on success, log the error field, surface message to the user, and only retry 429 / 500.

async function callLehnz(url: string, init?: RequestInit) {
  const res = await fetch(url, init);
  const body = await res.json();
 
  if (body.success) return body.data;
 
  console.error('lehnz error', { status: res.status, body });
 
  if (res.status === 429 || res.status >= 500) {
    throw new RetryableError(body.message);
  }
  throw new TerminalError(body.message);
}