Validation and errors

Use validation to reject an input before it changes application state. Use an application error to explain which kind of failure occurred without making your service depend on HTTP status codes.

Define a rule on the input

This complete input type can live in a module shared by the HTTP adapter and the application service. It requires iet-core and Serde with its derive feature.

use iet_core::{AppError, AppResult, ErrorKind, FieldError, Validate};
use serde::Deserialize;

#[derive(Deserialize)]
pub struct CreateNote {
    pub text: String,
}

impl Validate for CreateNote {
    fn validate(&self) -> AppResult<()> {
        if self.text.trim().is_empty() {
            let mut error = AppError::new(
                ErrorKind::Validation,
                "note.text_required",
                "A note needs some text",
            );
            error.fields.push(FieldError {
                path: "text".into(),
                code: "required".into(),
            });
            return Err(error);
        }
        Ok(())
    }
}

The rule belongs to the input, not to an Axum extractor. A command-line adapter or a test can use the same rule. Keep submitted values out of error codes and field metadata: a field name such as text is useful; repeating a password or private note in the response is not.

Validate at both boundaries

iet_http_axum::ValidatedJson<CreateNote> parses JSON and calls validate(). That protects the HTTP boundary. The service must still call input.validate()? before mutation, because not every caller goes through HTTP.

This is deliberate duplication of the check, not duplication of the rule. One implementation of Validate is called in both places.

JSON parsing errors are different from domain validation errors:

Outer body-limit middleware can reject a request before the extractor runs; do not assume every early middleware rejection has the extractor's problem body.

Convert errors only at the HTTP edge

Services return AppResult<T>. A handler returns a result whose error is iet_http_axum::ApiError; its From<AppError> implementation allows ? to do the conversion. The notes tutorial shows this in a handler.

ApiError produces application/problem+json with type, title, status, code, and errors. It does not serialize the application's free-form message. The validation error above becomes:

{
  "type": "about:blank",
  "title": "Validation failed",
  "status": 422,
  "code": "note.text_required",
  "errors": [{"path": "text", "code": "required"}]
}

Choose an error kind

For server errors, ApiError returns the generic code service.error and no field errors. Diagnostics are logged server-side instead of exposed to clients. Do not put secrets in an error message merely because it is not sent over HTTP: it may still be logged.

Source contract: crates/core/iet-core/src/lib.rs; HTTP behavior: crates/features/iet-http-axum/src/extract.rs and crates/features/iet-http-axum/src/error.rs.