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" }codigois the code, machine-readable and stable: clients branch on it. For domain errors,mensajeis 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 inmessages.ts).- Codes are
<entidad>.<error>, all lowercase:producto.no_encontrado,producto.validacion.<detalle>,cliente.email_invalido.
Status by error
Section titled “Status by error”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).
Errors that are not the entity’s
Section titled “Errors that are not the entity’s”| 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 |
Repository failures
Section titled “Repository failures”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.
Adding an error
Section titled “Adding an error”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");}