Skip to content

fix(api): report note endpoint failures with accurate status codes - #297

Open
0xGr1mm wants to merge 1 commit into
0xMiden:nextfrom
0xGr1mm:fix-note-endpoint-status-codes
Open

0xGr1mm wants to merge 1 commit into
0xMiden:nextfrom
0xGr1mm:fix-note-endpoint-status-codes

Conversation

@0xGr1mm

@0xGr1mm 0xGr1mm commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Summary

/get_note and /send_note answer every failure with 400 Bad Request, including failures the caller has no part in. The most consequential case is the note transport layer.

SendNoteError::NoteTransportError wraps the transport client, and none of NoteTransportError's variants describes a bad request:

variant what it means
Disabled the faucet was started without a note transport URL
Connection could not reach the transport service
Network the transport RPC failed
Deserialization the transport service answered with something unusable
PaginationDidNotTerminate the transport service's cursor never converged

All five are server-side or upstream conditions, and all five currently surface as 400. So while the note transport service is down, every /send_note call is recorded as a client error: it does not appear in server error rates, and it tells clients and proxies that retrying is pointless. Disabled has the same problem in a different way — it is a deployment that never configured the endpoint, which no caller can fix by changing their request.

NoteNotFound was also a 400 on both endpoints, even though the note id parsed and the request was well formed. The note is either not from this faucet or has been pruned from the cache after NOTE_RETENTION_BLOCKS.

Change

Give each failure the status it deserves:

  • NoteNotFound404 Not Found (both endpoints)
  • NoteTransportError::Disabled501 Not Implemented
  • every other NoteTransportError502 Bad Gateway
  • InvalidNoteId stays 400

Both error types now carry a status_code method, matching the shape GetTokenError already uses in get_tokens.rs.

Frontend

app.js switches on 400, 429, 500 and 503 and sends everything else to showRequestFailedError, so the new codes take that generic path. That is also an improvement in what the user sees: a transport outage currently renders as "Invalid request".

Tests

Six unit tests covering each mapping, including both an upstream failure and the disabled case.

  • cargo test -p miden-faucet --bins — 21 passed. frontend_mint_tokens fails in my environment because chromedriver is not installed; it is unrelated to this change and fails the same way on a clean next.
  • cargo clippy -p miden-faucet --all-targets --all-features -- -D warnings — clean
  • cargo +nightly fmt — clean

Note that this changes response codes on two public endpoints, so tell me if you would rather treat it as breaking and note it as such in the changelog.

@0xGr1mm
0xGr1mm force-pushed the fix-note-endpoint-status-codes branch from defacf7 to 41e70d4 Compare September 4, 2026 14:55
`/get_note` and `/send_note` answered every failure with `400 Bad
Request`, including failures the caller has no part in.

`SendNoteError::NoteTransportError` wraps the note transport client, and
none of `NoteTransportError`'s variants describes a bad request:
`Disabled` is a faucet started without a transport URL, and `Connection`,
`Network`, `Deserialization` and `PaginationDidNotTerminate` are all the
upstream service being unreachable or answering unusably. Reporting them
as 4xx means an outage of that dependency is recorded as the caller's
fault, so it does not show up in server error rates and tells clients not
to retry.

`NoteNotFound` was also a 400 on both endpoints, although the note id
parsed and the request was well formed.

Map them to what they are: 404 for a note that is not cached, 501 for a
transport layer that was never configured, 502 for one that failed.

The frontend switches on 400, 429, 500 and 503 and falls back to a
generic failure for anything else, so the new codes take that path
instead of telling the user their request was invalid.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@0xGr1mm
0xGr1mm force-pushed the fix-note-endpoint-status-codes branch from 41e70d4 to 8669da4 Compare September 8, 2026 16:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant