El contrato
Tres desenlaces, no dos
Un contrato de dos desenlaces obliga al tercero a disfrazarse de otro, y el disfrazado es siempre el que más tarda en entenderse. Bifurca una vez sobre status.
Última actualización
| status | HTTP | significado |
|---|---|---|
| done | 200 | Hecho. Lleva el output y la idempotencyKey. |
| pending_approval | 202 | Espera una firma humana y puede terminar horas después. Un webhook avisa cuando se resuelve. No reintentes. |
| refused | 4xx | No se hizo. reason es uno de una lista cerrada, y detail lleva lo que ayuda: para stale, un message que dice qué hacer. |
La forma de una respuesta
{ "status": "done", "output": { … }, "idempotencyKey": "…" }
{ "status": "pending_approval", "proposalId": "…", "idempotencyKey": "…" }
{ "status": "refused", "reason": "stale", "detail": { "why": "client_ambiguous", "message": "…" }, "idempotencyKey": "…" }Lecturas: dos desenlaces
Una lectura no cambia nada, así que nunca espera una firma: done (200) con el output, o refused (4xx) con un motivo con nombre. Tampoco lleva idempotencyKey.
{ "status": "done", "output": { … } }
{ "status": "refused", "reason": "role_forbidden", "detail": { "message": "…" } }