API Design — Founder OS

Standard Response Envelope

// Always use this shape — never break it
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;         // Machine-readable: "USER_NOT_FOUND"
    message: string;      // Human-readable: "No user with that ID exists"
    field?: string;       // For validation errors: "email"
  };
  meta?: {
    total: number;        // For paginated lists
    page: number;
    limit: number;
    hasMore: boolean;
  };
}

// Success example
{ "success": true, "data": { "id": "123", "name": "Alice" } }

// Error example
{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Email is invalid", "field": "email" } }

// Paginated list
{ "success": true, "data": [...], "meta": { "total": 500, "page": 2, "limit": 20, "hasMore": true } }

Error Code Standard

HTTP 400 — Bad Request      → Validation errors, malformed input
HTTP 401 — Unauthorized     → Not authenticated (no/invalid token)
HTTP 403 — Forbidden        → Authenticated but not permitted
HTTP 404 — Not Found        → Resource doesn't exist
HTTP 409 — Conflict         → Duplicate, state conflict
HTTP 422 — Unprocessable    → Semantically invalid (valid JSON, bad business logic)
HTTP 429 — Too Many Requests → Rate limit hit
HTTP 500 — Internal Error   → Something broke on server side

OpenAPI Spec Template