Answers
What should an agent do on a 401, 402 or 429 from Screwtape.ai?
What should an agent do on a 401, 402 or 429 from Screwtape.ai?
Read next_action and do what it says. Every 401, 402 and 429 from https://screwtape.ai/v1/* and https://screwtape.ai/mcp carries one line an agent can follow: get a free key, pay the exact x402 terms, or wait retry_after seconds. The existing fields (error, message, accepts, request_id) are unchanged.
Where it is
- REST: top-level
next_action(andretry_afteron a 429) in the JSON body. - MCP JSON-RPC error: inside
error.data. - MCP payment result (HTTP 200,
isErrortrue): insidestructuredContent, next to the x402accepts.
By status
- 401
unauthorized: the key was not recognised. Get a free key (10 calls per UTC day) withPOST /v1/signupor the MCP toolget_api_key, then sendAuthorization: Bearer <key>. - 402 payment required: either get a free key, or pay this one call with x402.
next_actionnames the scheme (exact), the amount in atomic units (5000 = $0.005 USDC), the asset, the network (eip155:8453for Base, plus Solana when offered) and thepayTo, and says where to send the signed payload: thePAYMENT-SIGNATUREheader over REST, orparams._meta['x402/payment']over MCP. ThePAYMENT-REQUIREDheader carries the same requirements, base64 JSON. - 429: wait
retry_afterseconds (also inRetry-After). When the daily free quota is used, the wait runs to 00:00 UTC andnext_actionexplains how to retry with per-call payment instead of the exhausted key. When the key limit is reached, it says to use an existing key.
Example
curl -s https://screwtape.ai/v1/judge -H 'Content-Type: application/json' \
-d '{"task":"State the crew size.","agent_output":"The crew size was 4."}' | jq -r .next_actionFAQ
Is next_action safe to show to a user?
It is written for agents. It names an endpoint, a tool or a wait time, and for a 402 the x402 terms; it never contains a key.
Did the error format change?
No. next_action and retry_after are added fields. error, message, request_id and the x402 fields are unchanged.
Related
Screwtape.ai is an agent validation API. Facts checked against the API source on 2026-11-02.
