Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Add a machine-readable error code to error responses

Aperta
  • Qualcosa non va?
#196 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
68/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
fastapi, python
Ambito
api, backend, documentation, testing

Direzione di ricerca

Read CONTRIBUTING.md first, then inspect app/exceptions/, app/app.py, app/models/, app/docs/, and tests/unit/test_openapi_docs.py. Run the relevant unit tests to establish the current response and OpenAPI behavior. Done means every non-200 response and documented example has a stable code, the README lists the codes, and the handler, subclass, and coverage tests pass.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

api enhancement

🔄 Updated for v5.0.0 (2026-10-08). Still open. 5.0.0 (#241) removed CSRFTokenError and added UpstreamError (502), so the code table is updated: CSRF_TOKEN_ERROR becomes UPSTREAM_ERROR. Each error now also carries a log-only detail, which must never be copied into the response.

Summary

Every error from pesu-auth has the same shape, {status: false, message, timestamp}. To react to a specific error (show "wrong password" and not "try again later", or retry only when PESU is down), a client has to match on the English message text, which breaks the moment a message is reworded. Add a stable, machine-readable code to every error response. This is an additive change, so it's a minor version.

Background

  • Errors are PESUAcademyError subclasses (app/exceptions/), each carrying its status_code. They're rendered by pesu_exception_handler in app/app.py.
  • Two other handlers build the same body: validation_exception_handler (400) and unhandled_exception_handler (500). The authenticate route also raises a bare PESUAcademyError(500) when the response model fails.
  • Swagger documents errors with ResponseModel (see app/docs/authenticate.py). tests/unit/test_openapi_docs.py checks that the examples validate against the model they name and match real responses.
  • 401 has two different causes (a wrong password, or a wrong /metrics token), and 502 has two (UpstreamError for the login, ProfileFetchError for the profile), so the status code alone isn't enough.

Proposed change

  1. Codes: a class attribute code: str on PESUAcademyError and each subclass, in UPPER_SNAKE_CASE:

    Code Status Raised by
    VALIDATION_ERROR 400 validation_exception_handler
    INVALID_CREDENTIALS 401 AuthenticationError
    METRICS_TOKEN_INVALID 401 MetricsAuthorizationError
    PROFILE_PARSE_ERROR 422 ProfileParseError
    UPSTREAM_ERROR 502 UpstreamError
    PROFILE_FETCH_ERROR 502 ProfileFetchError
    INTERNAL_ERROR 500 base class default, the unhandled handler, and the response-model failure

    New error classes from other issues add their own codes (for example UPSTREAM_TIMEOUT from #184, RATE_LIMITED from #190, SERVICE_UNAVAILABLE from #183); link this issue from those PRs.

  2. Model: add an ErrorResponseModel in app/models/ (strict, camelCase, like the others) with status: Literal[False], code, message and timestamp, and use it for every non-200 example in app/docs/*.py. Keep ResponseModel for 200s.

  3. Handlers: add "code" to the body in all three handlers.

  4. Contract: the README gets a table of codes and a sentence saying that codes are stable: they are never renamed or reused, only added. Messages may change.

  5. tests/unit/test_openapi_docs.py will need updating where it assumes errors use ResponseModel (for example test_the_profile_parse_422_is_kept); keep what each test is checking.

Tests

  • Every exception class has a unique code (a test that walks the subclasses).
  • Each handler emits code: 400, 401 (both kinds), 422, 502 (both kinds), 500 (unhandled).
  • The OpenAPI examples validate against ErrorResponseModel, and the "documented example matches a real response" tests still pass.

Acceptance criteria

  • Every non-200 response has a documented, stable code
  • Existing fields are unchanged, so current clients are unaffected
  • README and Swagger document the codes

How to contribute

  • Wait until you're assigned. Comment to ask for this issue, then wait for a maintainer to assign it to you before writing any code. PRs for unassigned issues are closed without review.
  • Read CONTRIBUTING.md first. It covers forking, setting up with uv, and running the tests.
  • Branch from dev in your fork, and open the PR against dev with a Conventional Commit title and Closes #196 in the description.
  • Bump the minor version in pyproject.toml and run uv lock (CI checks this). uv run pre-commit run --all-files must pass, and coverage must stay at 100%.
  • Update the README, app/docs/ and comments in the same PR as the behaviour they describe.
  • Never log, print, store or echo a password or token, including in tests, PR descriptions and screenshots.
Lingua principale
Python
Stelle
22
Fork
29
Merge medio
22h 1m
PR unite (30g)
20

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di pesu-dev/auth

Tutte le issue di pesu-dev/auth

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.