Skip to content

Error contract

Every error a Puerto API answers has the same body, RespuestaError from puerto-web:

{ "codigo": "producto.validacion.nombre_vacio", "mensaje": "producto.validacion.nombre_vacio" }
  • codigo is the code, machine-readable and stable: clients branch on it. For domain errors, mensaje is the same code. Errors are never sentences in the backend; turning a code into a sentence is the client’s job (the generated frontend does it in messages.ts).
  • Codes are <entidad>.<error>, all lowercase: producto.no_encontrado, producto.validacion.<detalle>, cliente.email_invalido.

Each entity’s error enum, Error<Entidad> in contextos/<c>/dominio/src/errores.rs, and the status a_respuesta_error in contextos/<c>/rest/src/errores.rs gives each variant:

Variant Code Status
Validacion(detalle) <entidad>.validacion.<detalle> 422
<Vo>Invalido (one per value object) <entidad>.<vo>_invalido 422
NoEncontrado <entidad>.no_encontrado 404
Duplicado <entidad>.duplicado 409
Prohibido (auth projects) <entidad>.prohibido 403
Repositorio <entidad>.repositorio 500
Desconocido <entidad>.desconocido 500

400 is left to poem, for a body it cannot parse. So a client can tell “malformed JSON” (400) from “the name is empty” (422) by the status alone (ADR-0007).

Status Code From
401 auth.no_autenticado BearerAuth: no token, or an invalid or expired one
401 auth.credenciales_invalidas local login
403 auth.prohibido #[requiere_rol]
503 auth.no_disponible the token could not be checked: the OIDC provider or the database is down
500 auth.no_configurado a protected route with no Autenticador registered

Repositories answer one ErrorRepositorio from puerto-nucleo, with one variant per outcome a use case treats differently. Each entity error converts from it (ADR-0015):

ErrorRepositorio Becomes Status
Duplicado <entidad>.duplicado 409
ReferenciaInexistente(campo) (a foreign key refused the write) <entidad>.validacion.<campo>_no_encontrado 422
DatosInvalidos (a stored row the domain rejects) <entidad>.repositorio 500
NoDisponible (the store failed) <entidad>.repositorio 500

ReferenciaInexistente only becomes a validation error in an entity with references; elsewhere it is <entidad>.repositorio. “Not found” is not a repository error: buscar_por_id answers Ok(None) and the use case decides.

Add the variant to the entity’s error enum with its #[error("…")] code. a_respuesta_error in contextos/<c>/rest/src/errores.rs has no catch-all arm, so the project does not compile until you give the new variant a status. Add its test next to the others, one per arm:

#[test]
fn deberia_mapear_validacion_a_422_con_su_codigo() {
// Actuar
let (status, Json(cuerpo)) =
a_respuesta_error(ErrorProducto::Validacion("nombre_vacio".into()));
// Comprobar
assert_eq!(status, StatusCode::UNPROCESSABLE_ENTITY);
assert_eq!(cuerpo.codigo, "producto.validacion.nombre_vacio");
}