Error Responses

Overview

Every error response from the folksbase API follows a consistent JSON shape. This makes it straightforward to build error handling in your client — you always know what to expect.

Error Shape

{
  code: string;       // Machine-readable error code (e.g., "VALIDATION_ERROR")
  message: string;    // Human-readable description
  details?: unknown;  // Optional additional context (e.g., Zod validation issues)
}

The code field is stable and safe to use in programmatic checks. The message field is for display purposes and may change between releases.

Error Codes

HTTP Status	Code	When
`400`	`VALIDATION_ERROR`	Request body, query params, or path params fail Zod validation
`401`	`UNAUTHORIZED`	Missing, invalid, or expired Bearer token
`404`	`NOT_FOUND`	Resource doesn’t exist or doesn’t belong to the user’s workspace
`429`	`RATE_LIMITED`	Request exceeds the global or upload rate limit
`500`	`INTERNAL_ERROR`	Unhandled server error

Validation Errors

When a request fails Zod validation, the details field contains the array of Zod issues. Each issue describes exactly which field failed and why:

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid request data",
  "details": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": ["email"],
      "message": "Required"
    },
    {
      "code": "invalid_string",
      "validation": "uuid",
      "path": ["id"],
      "message": "Invalid uuid"
    }
  ]
}

The path array tells you which field caused the error. Nested fields use dot-separated paths (e.g., ["custom_fields", "department"]).

Authentication Errors

Auth errors always return 401 with the UNAUTHORIZED code. The message varies depending on the cause:

// Missing or malformed header
{ "code": "UNAUTHORIZED", "message": "Missing or invalid Authorization header" }

// Expired or invalid token
{ "code": "UNAUTHORIZED", "message": "Invalid or expired token" }

// User has no workspace
{ "code": "UNAUTHORIZED", "message": "User has no workspace" }

// Generic auth failure
{ "code": "UNAUTHORIZED", "message": "Authentication failed" }

How Errors Are Handled

The API uses a global error handler middleware. Route handlers don’t catch errors themselves — they let exceptions propagate to the middleware, which formats them consistently. The middleware handles three categories:

Zod errors — caught by instanceof ZodError, returned as 400 with validation details
Auth errors — detected by message content ("Unauthorized" or JWT-related), returned as 401
Everything else — logged with stack trace, returned as 500 with a generic message

This means you’ll never see inconsistent error shapes across different endpoints. The format is always { code, message } with an optional details field.

Client Error Handling

A simple pattern for handling API errors:

const response = await fetch('/api/contacts', { ... });

if (!response.ok) {
  const error = await response.json();

  switch (error.code) {
    case 'VALIDATION_ERROR':
      // Show field-level errors from error.details
      break;
    case 'UNAUTHORIZED':
      // Redirect to login or refresh token
      break;
    case 'RATE_LIMITED':
      // Wait and retry (check Retry-After header)
      break;
    default:
      // Show generic error message
  }
}

The frontend already handles transient server errors (502, 503, 504) with automatic retry — one retry after a 1-second delay. Client errors (4xx) are never retried automatically.

Getting Started

Features

Architecture

Background Jobs

API

Deployment

Contributing

Overview

Error Shape

Error Codes

Validation Errors

Authentication Errors

How Errors Are Handled

Client Error Handling

​Overview

​Error Shape

​Error Codes

​Validation Errors

​Authentication Errors

​How Errors Are Handled

​Client Error Handling

Overview

Error Shape

Error Codes

Validation Errors

Authentication Errors

How Errors Are Handled

Client Error Handling