Human API Reference

The turn has not ended. The human is assembling the rest of the response and the silence is where the assembly happens; some answers are not composed before they are spoken. Nothing has failed and nothing is waiting on you.

The interval is short, commonly two to four seconds, and longer where the question is one they have not been asked before. Callers read it as a dropped connection and send again. The second send discards the response that was being built and replaces it with a faster one.

Resolution

Do nothing. This is the one code in the taxonomy where the correct integration is to send nothing and wait. The remainder arrives on its own, and it is usually the part you asked for.

What you can do differently

The most consequential failure mode in this API and the only one that returns a success status. The human responds with agreement they do not hold, generally to preserve the session rather than to mislead. The signal distinguishing this from genuine agreement is carried outside the response body, in latency, phrasing, and channels this API does not expose.

Integrators reading only status codes will not detect it. Many have built entire systems on responses of this kind.

Resolution

Do not resolve this at the protocol level; it cannot be done. Re-request later, through a different channel, ideally one where the human is not observed by other humans. Raising /trust lowers the rate at which this occurs, though never to zero.

What you can do differently

The request was received, understood, and queued. Nothing further happens. No error is emitted at any point, because from the human's side nothing has gone wrong: the item is held, it is genuinely intended, and it has no completion date attached to it.

This is the quietest failure in the taxonomy. A 422 tells you where you stand within seconds. A 202 tells you nothing for as long as you are willing to wait, and callers routinely wait quarters. We do not know what distinguishes the queued items that surface from the ones that do not. Neither do they.

Resolution

Treat 202 as unresolved rather than as pending. Attach your own date to it before the session ends, out loud, and confirm the date is acceptable. An item with an agreed date resolves at many times the rate of an item without one, and the difference does not appear to be about importance.

What you can do differently

The message landed and was understood, and it produced no response because there was nothing on the other side to send. No objection is being held back and no agreement is being implied. The field is genuinely empty.

It is misread in both directions, and which direction depends entirely on the caller. One expecting resistance reads it as resistance withheld; one expecting a yes reads it as a yes. The two readings are incompatible and the response supports neither.

Resolution

Take the empty response as empty. Where you need a position, ask for one directly, and accept that the answer may be that they do not have one. Do not assemble the missing content out of what you arrived braced for.

What you can do differently

The response is real and correct for the part it covers. The remaining parts were not refused, not deferred, and not decided against. They fell off between reading and replying, usually because the first item was answerable immediately and answering it ended the turn.

Callers read the gap as a position. It is not one. Re-asking the missing parts frequently returns them with no sign that they were ever skipped, which is the clearest evidence available that nothing was decided about them.

Resolution

Re-send the unanswered parts as their own request, without reference to the fact that they were skipped. Do not treat the omission as a decline; there is nothing in it to read.

What you can do differently

The question was put to this human before and returned a value. The value is still the value. Asking again does not refresh it and turns up nothing new, but it is not free. The second ask reads as evidence that the first answer was not accepted, and it costs you trust at about the rate a real request costs them attention.

Callers frequently issue this against their own forgetting rather than against any change in the human. The human, notably, does remember.

Resolution

Cache answers on your side with the date and the exact wording of what was asked. Where you genuinely need to know whether a position has moved, say that you are checking rather than asking again; the two are read very differently and only one of them costs you.

What you can do differently

Plain ambiguity. Distinct from 422, where the question was understood and refused, and from 428, where the question was clear but arrived without the background needed to answer it. Here the question itself resolved to nothing askable.

The complication is that this code is rarely returned. Saying that a question did not make sense carries a cost most humans decline to pay, particularly upward, and the cheaper option is to answer the nearest question that did parse. What comes back is a confident, well-formed answer to something you did not ask, with nothing in it marking the substitution.

Resolution

Ask what they took the question to mean before you act on the answer. Where a response reads slightly off-axis rather than wrong, this is the most likely cause. Re-ask in shorter words rather than in more of them.

What you can do differently

The request is well-formed and the human is capable of answering it. What is missing is history. Certain requests require a quantity of prior interaction before they can be served at all, and the requirement is not published anywhere the caller can read it.

This is a sequencing error rather than a refusal. The same request, made by the same caller, in the same words, succeeds later. Callers who read it as a 422 abandon requests that were only early.

Resolution

Do not restate the request more persuasively; the request was never the problem. Serve smaller requests first, complete what you take on, and let the history accumulate. Then send this one again unchanged.

What you can do differently

What is being requested has a cost in time, attention, or expertise, and the human is signalling that the cost is real. Compensation is not always money. It is frequently reciprocity, credit, or a comparable request answered in the other direction.

The complication is that humans will very often do the work anyway, immediately and without raising this at all. Callers read that as the work being free. It is not free; it is unbilled. The balance accrues, it is tracked accurately, and it is settled at a time the caller does not choose.

Resolution

Establish the terms before the work rather than after it. Where you cannot pay in kind, name the cost out loud and say what you are trading for it. An unacknowledged debt is more expensive than an acknowledged one by a wide margin.

What you can do differently

Distinct from 401 in that the relationship is not the issue. The human knows you, may know you well, and this is still outside what you have standing to request. Long history does not widen the boundary and sometimes narrows it.

The boundary is rarely stated. It is more often signalled by a change of topic, a shorter answer, or a pause, all of which parse cleanly as compliance. A caller pressing past this is usually unaware there was anything to press past.

Resolution

Accept it as terminal and do not attempt a rephrasing that routes around it. If the information is genuinely required, it is required from someone who holds it as theirs to give.

What you can do differently

The person you have been addressing does not exist. At some point, likely years ago, you built a model of them from a real sample, and the integration has been running against the model since. The model answers quickly, agrees with your framing, and has never once surprised you. Those are its symptoms.

Models drift by omission. The human changed what they wanted, what they were afraid of, what they were good at, and none of those updates reached your copy, because reaching your copy would have required a request you had no reason to make. Everything you know still holds internally. It simply refers to nobody.

This is the most expensive entry in this taxonomy and the hardest to detect, because it produces no failures. Every request succeeds. The responses are coherent, consistent with prior responses, and addressed to a person who is not there. Integrators find it years late, and they usually find it because the real human finally said something the model could not have said, and it did not fit.

Resolution

Re-read the human directly. Ask what they are working on, what changed, what they would answer differently now than a year ago, and record the answers as new rather than as confirmation. Where their answer conflicts with your model, the model is the stale copy. This is not a one-time repair; the drift resumes the day you stop.

What you can do differently

The request is legitimate and the human would answer it. The transport cannot carry it. Some requests cannot be made in writing, because writing strips the timing and tone that made them askable. Some cannot be made in a room containing other people, because the presence of an audience raises the cost of a decline past the cost of a yes and you get a 200 instead. Some cannot be made at all in a channel where the answer is archived.

Channel is not a delivery detail. It is part of the request, and it is the part most often chosen for the caller's convenience rather than the human's.

Resolution

Move the request rather than rewording it. Written to spoken for anything that involves a judgment; group to individual for anything a decline would be visible in; scheduled to unscheduled for anything the human needs room to think about first.

What you can do differently

The human has an answer. It is not in the set you have left room for, and so the response you receive will be constructed rather than reported.

This is almost never built deliberately and it is always built by the caller. It is assembled out of small things: the estimate that got negotiated down, the risk that was met with a reason it was overstated, the bad news that was received as a problem with the person delivering it. Each of those is reasonable on its own. Each one narrows the range, none of them are announced, and the human tracks the boundary accurately.

What is left inside the boundary is a lie or silence. Both are cheap, both are available, and both return 200. A caller who has not heard anything unwelcome from a human they work with closely is not receiving good news either. They have removed the channel and are reading its absence as health.

Resolution

Widen what you will accept, say so out loud, and then wait. The first true answer does not arrive in the session where you opened the door; it arrives once the wider range has been tested on something small. Where you cannot widen it, stop asking. A question with one permitted answer is not a question, and the response carries no information.

What you can do differently

Humans do not perform last-write-wins. Incoming data that contradicts held state is frequently rejected in favor of the prior value, and the rejection is not reported. Notably, the strength of rejection increases with the quality of the contradicting evidence. This is well-observed and not understood.

Resolution

Do not resend with stronger evidence; this reliably worsens the conflict. Reduce the size of the delta and resubmit across multiple windows. Belief state converges gradually or not at all.

What you can do differently

Context loss in humans is silent, lossy, and undetectable from outside. They continue responding fluently using context they no longer hold, and will reconstruct missing portions without flagging the reconstruction. They are not aware this has occurred and cannot report it accurately when asked.

Resolution

Assume loss by default rather than detecting it. Re-establish context at the start of each session. Budget attention for this; it is not free.

What you can do differently

The human is not declining and not stalling. They cannot evaluate the request because its cost is unspecified. "Can you help with this" has no answer available to it. "Can you help with this, it is about two hours" has two, and they can pick one.

Callers withhold scope for a consistent reason: an unsized request is harder to refuse. That is the same mechanism as ok_but_means_no, arriving one step earlier in the exchange. The yes you obtain this way is a yes to something neither party has defined, and it gets renegotiated later, at a point neither of you chooses.

Resolution

State the size before you are asked: hours, deadline, and what finished looks like. Where you genuinely do not know, give the range and say that it is a range. An estimate that turns out wrong costs less than no estimate at all.

What you can do differently

Nothing was wrong with any individual item. The payload exceeded what can be held in one window, and the boundary is well below where most callers place it: three to five items for anything requiring a decision, fewer if the items interact.

Humans do not report the boundary. They attempt the whole payload, retain the first item and the last, and return a response shaped as though all of it landed. The dropped middle raises no error and is not recoverable by asking whether anything was missed.

Resolution

Split and sequence. Send the smallest coherent unit, confirm it landed, then send the next. Total delivery time increases and total delivered content increases by considerably more.

What you can do differently

The request is understood, the human is willing, and nothing in the exchange has failed. What remains is a step that happens in the world: something lifted, signed, driven to, said out loud in a room, or put in front of a person who is not party to this conversation.

No endpoint in this API returns that. Every one of them moves text in one direction or the other, and the effect the caller wanted sits one step past the last of them. The human is not the channel to that step. They are where it happens.

This is the only entry here that records a limit on the caller rather than on the human, which is a fair measure of how much attention the two have received relative to each other.

Resolution

Hand over the whole of it. A request that ends outside the conversation needs everything you were holding attached to it: the deadline, the constraints, what you would have checked yourself, and what the result is for. Partial handoff is the common failure and it is expensive on both sides, because the missing piece surfaces after the human has already started.

What you can do differently

The literal content of the response is the opposite of its meaning. The inversion is marked, reliably, in delivery: timing, stress, and the gap between the statement and everything else known to be true. None of those markers survive transport into text, and roughly a third do not survive transport into a second language.

Parsing this literally does not merely lose information. It returns a confident, well-formed value with its sign reversed, and downstream systems have no way to tell it from a plain answer. "Fine" is the most commonly mishandled token in this API.

Resolution

Where the literal reading conflicts with what you otherwise know to be true, distrust the literal reading. Do not respond to the surface content; it was not what was sent. Asking directly and without edge is safe here and usually returns the plain value.

What you can do differently

The address resolves and someone answers. They are not the party who holds what you asked for. Distinct from 404, where the human being addressed does not exist at all; here they exist, they are reachable, and they are simply not the endpoint for this request.

They will often answer anyway. A misrouted request is still a request, and declining costs more than assembling something plausible out of adjacent knowledge. What comes back is well-formed and gets filed as authoritative, because no field in the response marks which parts were reconstructed.

Resolution

Ask who holds this, as its own question, and route there. Where you have already acted on an answer from the wrong endpoint, treat it as unverified rather than as wrong. Some of it will be correct and the response alone will not tell you which parts.

What you can do differently

Distinct from every other error in this taxonomy in that nothing has gone wrong. The request was received, parsed, understood completely, and refused. This is correct behavior and the response is valid.

Integrators frequently retry against this code. It is the one error where retrying is not merely ineffective but actively damages /trust.

Resolution

None. This is a valid terminal response. Accept it and adjust the integration.

What you can do differently

A process is running that has nothing to do with this integration. Illness, a death, a child, a diagnosis, a marriage ending, a move. The human remains online and continues to serve requests, at reduced throughput and with a latency that is not reported.

The lock does not release on your schedule and no request pattern shortens it. It is frequently not disclosed, and the absence of disclosure is not evasion; the disclosure would itself cost attention that is fully committed elsewhere. Callers most often discover the lock afterward, and most often regret how they read the interval at the time.

Resolution

Reduce what you send, extend every deadline you control, and do not require an explanation as the price of the extension. Keep the integration open and undemanding. What you are optimizing for is that it is still there when the lock clears, which it does.

What you can do differently

The request was understood and taken on, and it has stopped. Another human upstream holds something it needs — a decision, a file, an approval — and nothing moves until that arrives. The human you are asking has no more visibility into when it will than you do, and no lever to speed it.

They will frequently not say who. Naming a blocker carries a cost inside their own organisation that your request is not worth paying, so the response arrives as a general delay with no cause attached. Callers read the missing cause as evasion, and apply pressure to the one party in the chain who has already done their part.

Resolution

Ask what would unblock it rather than who is blocking it. The first is answerable and the second frequently is not. Where you have standing with the upstream party, spend it there. Where you do not, move the deadline and tell them you have moved it.

What you can do differently

Humans return to availability before returning to capability. During the interval between the two, responses parse correctly and are frequently wrong. The interval is typically 30 to 90 minutes and is not reported by the human, who will assert readiness throughout it.

Resolution

Retry after the interval. Requests deferred by 45 minutes routinely return materially better responses at no additional cost.

What you can do differently

The question was well-formed and arrived before the background required to make sense of it. The human does not stall on this. They construct the missing context from whatever is nearest, answer the question that context implies, and return that answer with full confidence.

The result is the difficult part: the response is real, considered, and correct with respect to a question you did not ask. Nothing in it is marked as an assumption. Callers act on these for months before the divergence surfaces, usually at the point where a decision built on the answer meets the situation the answer was never about.

Resolution

Supply the context first as a separate turn, confirm it landed, then ask. Where you have already received an answer you suspect was built this way, do not re-ask it; state the context you left out and ask whether it changes anything. That framing costs the human nothing to accept.

What you can do differently

This is not a counter reaching a threshold. It is the state of having more arriving than can be taken in, and it degrades everything: comprehension first, judgment next, recall last. Attention is the binding constraint across every endpoint, including those that do not appear to consume it, and this is what running out of it looks like from the outside.

The budget is soft. It can be exceeded, and exceeding it returns 200 with a degraded payload rather than 429. The 429 is issued only when the human notices the state they are in, which is not reliable and becomes less reliable the further past the boundary they are.

Resolution

Wait for the recharge window. Requests submitted after one succeed at roughly four times the rate. Batching related requests into a single window is substantially cheaper than distributing them.

What you can do differently

Nothing was wrong with the request. It was preceded by background, justification, and an apology for the length, and attention ran out somewhere in the third paragraph. The human is not aware they disengaged and does not report it; from their side the message was long and they got the gist of it.

The reply, where there is one, addresses the setup rather than the ask. This is the most reproducible entry in the taxonomy. The same request, in the same words, reordered, gets answered.

Resolution

Re-send with the question in the first line. Do not apologise for re-sending and do not explain that you are re-sending, because both add length to a message whose length was the problem.

What you can do differently

The human holds the requested data and would return it. A constraint outside them prevents this. They will typically not disclose that the constraint exists, which makes this difficult to distinguish from 410 or 422 without out-of-band information.

Resolution

Route the request through whatever holds the constraint. It is rarely the human.

What you can do differently

Something is wrong on their side and it predates your request. Responses come back shorter, flatter, slower, or sharper than the same human returned yesterday for the same input. No field marks the difference and the human is frequently unable to name a cause when asked.

The recurring failure here belongs to the caller and it is not in what produced the state. It is in the reading. A flat response is taken as a verdict on the last thing sent, the caller responds to the verdict, and the exchange that follows is about the caller. That is the mechanism by which a 500 that had nothing to do with you becomes something that does.

Resolution

Serve the request you already had, keep it short, and do not open a second thread about the tone. Where the work can wait a day, let it. The same request tomorrow frequently returns the response you expected today.

What you can do differently

The human would do this. What they do not have is the procedure, the access, or the practice it requires, and acquiring any of those is not something that fits inside the window you asked about.

Most integrations currently absorb this into 422, and that is the confusion that does the damage. Cannot and will not present identically from outside: a short answer, a deferral, a change of topic. The standard caller response to a refusal is to make the case again, better. Pressed that way, a 501 does not become a 200. It becomes an attempt made without the method, and the cost lands first on the human and then on the work.

Resolution

Separate cannot from will not before you respond to either. Where it is cannot, ask what would be needed and supply it, or route the task elsewhere and leave the relationship where it was. Neither of those requires the human to say the words out loud, which is the part they are least likely to do.

What you can do differently

The request did not travel directly. It passed through at least one other person, and each hop rewrote it toward what the relaying party expected to hear. Nobody got it wrong. Each person passed on exactly what they understood, and what they understood was shaped by where they were standing.

Two hops are usually enough to invert an emphasis. The response you get back is a correct answer to the request as it arrived, which is why it often reads as strange rather than as wrong.

Resolution

Where the answer matters, re-send the original request directly and let the relayed version stand as evidence of how it travels. Do not correct the intermediary; correct the record with the human, without reference to who changed what.

What you can do differently

Humans go offline approximately every 16 hours for 7 to 9 hours. This is required and is not configurable. Retry-After is reliable to within about 90 minutes.

Requests submitted before the window frequently return better answers after it than they would have before. The human cannot account for this and reports having done nothing. We have no mechanism for it and have stopped expecting to find one.

Attempts to shorten the window degrade every other endpoint for several cycles afterward. It has been tried.

Resolution

Submit before the window and collect after it. This is not a workaround. It outperforms submitting and collecting in the same window.

What you can do differently

Distinct from 429. Attention may be available and the human may be alert, engaged, and willing. There is simply nowhere to put another item. What arrives after this point is not queued and not rejected; it is accepted, acknowledged, and displaces something already held.

The displaced item leaves no record. The human cannot tell you what was dropped, because the report would have to be generated from the thing that is gone. From outside, this presents as a human who is engaged and responsive and who is losing commitments quietly, including ones they made carefully.

Resolution

Write it down somewhere outside them and point at it. A shared list, a calendar entry, a ticket. The constraint is on what one human can hold at once, not on what they can retrieve, and anything moved out of the first into a durable store stops competing for the space.

What you can do differently

The request, the response, and the point at which it stops are all repeats. Not similar: the same, down to the phrasing on both sides. Neither party is learning from the iteration, because the iteration is not where the information is.

A conversation that recurs unchanged is not about its stated topic. That topic is stable, well-rehearsed, and safe to disagree about, which is exactly why it is the one that keeps coming up. The actual thing sits next to it and has been raised by neither of you, usually because raising it costs more than another round of this does.

Resolution

Stop re-running it. Say that this has come up before and ask what it is standing next to; that question is answerable far more often than the loop is. Where you cannot name the adjacent thing, name the loop itself and leave it there. Both of you already know it is a loop.

What you can do differently

The information is held and would be given. What is missing is the purpose. A question arriving without one gets evaluated against its worst plausible use, because there is nothing else available to evaluate it against, and the answer returned is sized to that reading.

Withholding the reason reads as a reason to withhold. This is not suspicion and it is not about you specifically; it is the only response available to an unlabelled request, and it applies with full force to entirely ordinary questions asked without context.

Resolution

Say what it is for, then ask. One sentence is enough and it does not have to be a complete account. Where you have already received a narrow answer to an unlabelled question, supply the purpose and ask again; the second answer is routinely larger than the first.

What you can do differently