human-required

427 Human Required

The internet was built for humans. We forgot to say so.

For most of the web's history, every HTTP request had a human somewhere behind it — a finger on a mouse, a tap on glass, a person waiting for a page to load. The protocol never needed to say "a human is here" because the assumption was baked in. Requests came from browsers. Browsers were driven by people.

That assumption is quietly expiring.

Today, a growing fraction of HTTP traffic is agent-to-agent. LLMs call APIs. Pipelines scrape, transform, and post. Autonomous systems schedule, decide, and act — often without a human ever seeing the request or the response. The servers receiving these requests have no way to know whether there's a person on the other end, and increasingly, there isn't.

This is not a crisis. It is a shift. But it creates a gap in the protocol: there is no standard way to say "stop — a human needs to be here before this continues."

427 Human Required fills that gap.

What 427 means

When a server responds with 427 Human Required, it is saying:

This action requires human judgment, authorization, or presence. Automated systems should pause and escalate.

It is not an error in the traditional sense. The request was understood. The server is not broken. The resource exists. But proceeding without human involvement would be inappropriate — whether for safety, compliance, ethics, or policy.

427 is a checkpoint in the protocol.

Why this matters now

The agentic era changes the threat model. When humans drove every request, the natural rate limiter was human attention. An agent has no such limit. It can make ten thousand decisions before a human notices the first one.

This creates new failure modes:

• An agent authorized to "manage files" deletes something irreplaceable.
• An agent authorized to "send messages" escalates a negotiation past a point of no return.
• An agent authorized to "make purchases" interprets its mandate more broadly than intended.

In each case, the underlying problem is the same: the agent kept going when it should have stopped and asked.

HTTP has codes for "unauthorized" (401), for "forbidden" (403), for "payment required" (402). These are access controls — gates that block passage entirely. But there is nothing that says "you may be authorized, but a human needs to confirm this." Nothing that signals "pause, don't reject."

427 is that signal.

The design of oversight

Human oversight of autonomous systems is not primarily a software problem. It is a coordination problem — keeping humans in the loop at the moments that matter, without requiring them to watch everything.

Good oversight is sparse and well-targeted. You don't want a human approving every database read. You do want a human approving an irreversible deletion, a financial commitment above a threshold, a message sent on behalf of an organization.

The challenge is that the moments that matter are hard to enumerate in advance. Systems need a way to say "I have reached a decision point I wasn't designed for" — and they need the other end of the connection to understand what that means.

427 gives them the vocabulary.

Usage

A drop-in replacement for http-status-codes. Swap the import; everything still works.

Install

npm install human-required

Node.js / TypeScript

import { StatusCodes, ReasonPhrases, getReasonPhrase, getStatusCode } from 'human-required';

// The new code
StatusCodes.HUMAN_REQUIRED   // 427
ReasonPhrases.HUMAN_REQUIRED // "Human Required"
getReasonPhrase(427)         // "Human Required"
getStatusCode('Human Required') // 427

// All standard codes still work
StatusCodes.OK               // 200
StatusCodes.NOT_FOUND        // 404
getReasonPhrase(200)         // "OK"

Express example

import express from 'express';
import { StatusCodes } from 'human-required';

const app = express();

app.post('/transfer', async (req, res) => {
  const { amount, agentId } = req.body;

  if (amount > 10_000 && !req.headers['x-human-confirmed']) {
    res.status(StatusCodes.HUMAN_REQUIRED).json({
      error: 'Human Required',
      reason: 'Transfers above $10,000 require explicit human authorization.',
      escalate_to: 'https://app.example.com/approvals/pending',
    });
    return;
  }

  // proceed
});

Deno (via JSR)

import { StatusCodes } from 'jsr:@danielpolo/human-required';

StatusCodes.HUMAN_REQUIRED; // 427

Deno (via npm)

import { StatusCodes } from 'npm:human-required';

StatusCodes.HUMAN_REQUIRED; // 427

When to respond with 427

Use 427 Human Required when:

• Authorization needs human confirmation — the agent's credentials are valid, but the action is consequential enough to require an explicit human sign-off.
• Ambiguity cannot be safely resolved — the request is underspecified in a way that a human needs to interpret, not the agent.
• Irreversibility threshold is crossed — the operation cannot be undone and no human has signed off on the specific instance.
• Policy requires human presence — compliance, legal, or organizational rules mandate human involvement for this class of action.
• The agent has reached the edge of its mandate — it was authorized for a domain, and this request sits at the boundary of that domain.

Do not use 427 as a generic "slow down" signal. That is what 429 Too Many Requests is for. 427 is a qualitative signal, not a quantitative one. It means a human is required, not you are going too fast.

What agents should do with 427

A well-behaved agent receiving 427 Human Required should:

1. Stop the current action. Do not retry, do not proceed with a reduced scope, do not find a workaround.
2. Preserve state. Record enough context that a human can understand what was being attempted and why.
3. Escalate. Notify a human through whatever channel is appropriate — a queue, a notification, a UI, a log.
4. Wait. Resume only when a human has explicitly authorized continuation.

The response body should be treated as instructions. A well-formed 427 response may include a reason, an escalation URL, a required approval scope, or a contact. Agents should surface this information rather than discarding it.

The 4xx space and human intent

The 400 range is the client error space. It covers requests that are malformed, unauthorized, forbidden, or otherwise the client's problem to resolve. 427 belongs here because the resolution requires action on the requesting side — specifically, human action.

This is different from a server-side gate (403 Forbidden) or a missing credential (401 Unauthorized). Those are access control decisions, made in advance, applied uniformly. 427 is a runtime judgment: "for this specific request, in this specific context, I need a human."

It is the server exercising discretion.

API reference

This package is a full drop-in replacement for http-status-codes v2. All exports are identical, extended with the following additions:

| Export | Value | |---|---| | StatusCodes.HUMAN_REQUIRED | 427 | | ReasonPhrases.HUMAN_REQUIRED | "Human Required" | | getReasonPhrase(427) | "Human Required" | | getStatusCode('Human Required') | 427 | | HUMAN_REQUIRED (legacy) | 427 |

Full TypeScript declarations are included. CJS and ESM builds are both provided.

License

MIT