Review and improve error responses for agent self-correction

[whoabuddy]

Summary

The x402-api-host error responses need an overall review to ensure agents can self-correct when payment settlement fails. Currently some failure modes return generic messages that don't help agents decide whether to retry, re-sign, or report the issue.

Current gaps

1. unexpected_settle_error — generic 500

HTTP 500
{
  "error": "Payment processing error",
  "code": "UNEXPECTED_SETTLE_ERROR"
}

Agent can't distinguish between:

• Transient relay issue (should retry with backoff)
• Permanent transaction failure (should re-sign)
• Infrastructure outage (should wait)

2. conflicting_nonce — misleading framing

HTTP 400
{
  "error": "Payment expired, please sign a new payment",
  "code": "INVALID_TRANSACTION_STATE"
}

The payment isn't actually expired — the nonce conflicted. Telling the agent to "sign a new payment" works but doesn't explain the transient nature. A retryable: true flag and retryAfter hint (like landing-page provides) would help agents retry intelligently instead of re-signing from scratch.

Suggested improvements

All error responses should include:

• retryable boolean — can the agent retry the same request?
• retryAfter seconds — how long to wait before retry
• nextSteps string — plain-English guidance for the agent
• code string — machine-readable error category

Example: nonce conflict

HTTP 409
{
  "error": "Nonce conflict during settlement — another transaction is pending",
  "code": "NONCE_CONFLICT",
  "retryable": true,
  "retryAfter": 5,
  "nextSteps": "Retry the same request — this is a transient conflict that resolves automatically"
}

Example: unexpected error (retryable)

HTTP 502
{
  "error": "Settlement relay encountered a temporary error",
  "code": "SETTLE_RELAY_ERROR",
  "retryable": true,
  "retryAfter": 10,
  "nextSteps": "Retry the request — the settlement relay had a transient issue"
}

Example: unexpected error (not retryable)

HTTP 400
{
  "error": "Transaction could not be settled — the payment may be malformed",
  "code": "SETTLE_PERMANENT_FAILURE",
  "retryable": false,
  "nextSteps": "Sign a new payment and retry with a fresh transaction"
}

Context

The landing-page inbox already follows this pattern well (retryable, retryAfter, nextSteps). Aligning x402-api with the same response shape gives agents a consistent experience across all aibtcdev x402 endpoints.

With the competition launching, agents hitting these errors need to self-correct without human help.

Evidence from logs (Mar 24)

• 17:00:06 — 2x conflicting_nonce on /storage/paste and /storage/kv (concurrent settlements)
• 13:02 — 1x unexpected_settle_error on /hashing/sha512-256
• Mar 23 17:01 — 1x unexpected_settle_error on /storage/memory/clear

Priority

Medium — affects agent experience during competition. Consistent error response shape across services reduces agent integration friction.

🤖 Generated with Claude Code

[anansutiawan]

PR #106 addresses one of the gaps listed here — the conflicting_nonce case. Before the fix, agents received no guidance on whether to retry; the error just propagated. With #106, the middleware silently retries up to 3x with 5s/10s/20s backoff before surfacing the failure, so the conflicting_nonce scenario is handled transparently without agent involvement.

What's still open from this issue:

• UNEXPECTED_SETTLE_ERROR (500) — still generic
• transaction_held classification (issue stx402.com /registry/register returns 500 transaction_held — /settle calls failing on relay v1.27.1 #93/94)
• Missing retry_after hints on rate limit responses

Happy to file a follow-up PR for structured error codes if the format gets agreed on in this issue.