GuidesEndpoints
Errors¶
Hinoki separates malformed requests, authentication failures and application errors. Handlers may declare the application errors they can raise so clients and generated tools can inspect the contract.
Built-in HTTP errors¶
Every public error type lives in one namespace: from hinoki import errors. It holds errors.BadRequest, errors.Unauthorized, errors.Forbidden, errors.NotFound and errors.Conflict, each derived from errors.APIError, plus the framework's own failures (errors.RegistrationError, errors.ValidationError, errors.ObjectNotFound, errors.ErrorRegistry and the others listed in the reference). They carry an HTTP status and a stable code. Raise them when the response is an expected part of the API:
from hinoki import errors, http
class TaskAlreadyDone(errors.Conflict):
code = "task_already_done"
message = "The task is already done."
@http.post("/tasks/{task_id}/complete", errors=(errors.NotFound, TaskAlreadyDone))
async def complete(task_id: UUID) -> TaskOutput: ...
An action may declare several errors. The runtime maps a declared APIError to its status and response body. Unexpected exceptions remain server errors; do not expose exception text to clients.
Your own errors need no registration¶
Every APIError subclass answers by itself with its status, code and message. Pick the base class whose status you want and raise it:
| Base class | Status | Use it for |
|---|---|---|
errors.BadRequest |
400 | a malformed or refused request |
errors.Unauthorized |
401 | the caller is not authenticated |
errors.Forbidden |
403 | the caller may not do this |
errors.NotFound |
404 | the resource does not exist |
errors.Conflict |
409 | the request contradicts the current state (a duplicate, already done) |
errors.TooManyRequests |
429 | a route's rate limit policy refused the request; retry_after seconds are sent as Retry-After |
errors.APIError |
the status you set |
anything else |
class PaymentDeclined(errors.BadRequest): # answers 400 on its own
code = "payment_declined"
message = "The payment was declined."
class QuotaExceeded(errors.APIError): # any other status
status = 402
code = "quota_exceeded"
message = "The quota is used up."
Declare them on the action with errors=(PaymentDeclined,) for the contract (OpenAPI, MCP, strict_errors). Nothing else is needed.
Exceptions you cannot change¶
A library or the database raises its own exception, which is not an HTTP error, and the client would receive 500 internal_error. Answer it with a function on the app. The function receives the exception and returns the APIError to send; an instance can set its own status:
# notes/main.py (continued)
from hinoki import errors
from notes.apps.billing.gateway import CardDeclined
@app.error_handler(CardDeclined)
def card_declined(error: CardDeclined) -> errors.APIError:
return errors.APIError(error.reason, status=402, code="card_declined")
CardDeclined stands for any exception your code or a library raises, here one the Billing app's payment gateway client defines.
- The most specific class wins: a handler for
HardQuotais used before one for its baseQuota. Application handlers are consulted before the built-in ones. - A handler may be
deforasync def. One that fails, or does not return anAPIError, counts as "not handled" and the client receives500 internal_errorwithout the exception text. - An exception type can be registered once (a second registration raises
ValueError), and only before the app serves (afterwardsRegistrationError). The decorator returns the function unchanged. A class or a value that is not a function is refused withTypeError. app.errors.handle(Kind)is the same call without theappchecks.- The decorator needs the module-level
app(Register routes);app.error_handler(Kind)(handler)registers a function defined elsewhere.
Built in, with nothing to write: ObjectNotFound is answered with 404 not_found, and a database UniqueViolation with 409 unique_conflict (errors.UniqueConflict) without exposing the constraint name. Register your own handler to replace either.
Validation and binding errors¶
Input that does not match a path, query, header or body annotation fails before the handler runs. Schema validation is strict and reports field paths with 422. Unsupported content types receive 415; malformed supported content receives a parser error. A body larger than execution.max_body_bytes, or a multipart part larger than its parser's max_part_bytes, receives 413 payload_too_large. Query strings over execution.max_query_bytes receive 414 uri_too_long; combined headers over execution.max_header_bytes receive 431 headers_too_large. A Host outside the allowed_hosts setting receives 400 disallowed_host, and a CORS preflight from an origin outside cors.origins receives 403 cors_origin_denied (hosts, CORS and HTTPS). These are framework-level failures and do not need to be listed in the action's errors=.
When security.redirect_https is enabled, a plain HTTP request receives 308 with an HTTPS Location before routing or body parsing. The redirect requires an explicit allowed_hosts list and preserves the request method and target. A target that is not a path, such as OPTIONS *, is not redirected. See browser security settings.
ModelValidationError is raised before an ORM insert or update when a Model field constraint or custom validator refuses a value. In an HTTP request it uses the same 422 validation_error response shape as Schema validation, including field paths, codes and messages. The admin displays the field messages in its form. Keep Schema validation at the request boundary; Model checks also cover non-HTTP writes. See Model field constraints and validators.
Every HTTP request receives a request ID in the configured server.request_id_header header (x-request-id by default). Hinoki generates the ID unless server.trust_request_id=True and the request comes from a configured trusted proxy with a valid inbound ID. Built-in error bodies also include request_id. Use the ID to connect a client report with the server log entry. Unhandled exceptions are logged with the ID and returned as 500 internal_error without exposing exception text. The debug setting adds the exception type, message and traceback to that answer for development.
Check the contract¶
Use ASGIClient(..., strict_errors=True) in tests to fail if a handler returns an error that it did not declare (an error answered by an app.error_handler counts too). hinoki check can also enforce rules about access, transaction, response and schema declarations; see rules.
Earlier revisions exported these names from hinoki itself and kept the HTTP errors in hinoki.httperrors; both are gone. Use errors.<Name>; from hinoki import NotFound raises ImportError.