Códigos de error

Los errores de negocio traen un code estable en el cuerpo. Úsalo en tu lógica en lugar del message, que puede cambiar. La estructura del error está en convenciones.

const res = await fetch(url, opciones);
if (!res.ok) {
  const error = await res.json();
  switch (error.code) {
    case 'HALLAZGOS_PENDIENTES':
      return mostrar('Justifica los hallazgos pendientes antes de certificar.');
    case 'DOCUMENTO_NO_LISTO':
      return reintentarEnUnosSegundos();
    default:
      throw new Error(`${error.statusCode}: ${error.message}`);
  }
}

Alta y documentos

Código	HTTP	Cuándo	Cómo resolverlo
`PDF_INVALIDO`	`400`	El base64 no contiene un PDF (p. ej. una imagen o un archivo dañado).	Envía el PDF original, codificado completo.
`PDF_PROTEGIDO`	`400`	El PDF está cifrado con contraseña.	Quita la protección antes de subirlo.
`FOLIO_NO_DETECTADO`	`422`	El PDF no trae un folio legible en la carátula.	Revisa la carátula del PDF y vuelve a subirlo.
`FOLIO_YA_EXISTE`	`409`	Ya hay un avalúo con el folio leído del PDF.	Consúltalo con `GET /v1/avaluos/{folio}` o sube una versión nueva con `POST …/documento`.
`FOLIO_NO_COINCIDE`	`422`	El PDF re-subido es de otro folio.	Sube el PDF correcto o usa el folio de ese PDF.
`DOCUMENTO_DUPLICADO`	`409`	El PDF re-subido es igual a una versión ya subida a ese avalúo.	Sube el documento con las correcciones.
`INSTITUCION_NO_DETECTADA`	`422`	No se pudo leer la clave de entidad otorgante (campo 1.16) del PDF.	Revisa que el campo esté completo.
`INSTITUCION_NO_VALIDA`	`422`	La clave del campo 1.16 no está activa en el catálogo.	Ver instituciones.
`TIPO_INMUEBLE_NO_DETECTADO`	`422`	No se pudo leer el campo 1.10 del PDF.	Revisa que el campo esté completo.
`TIPO_INMUEBLE_NO_VALIDO`	`422`	El tipo de inmueble del PDF no está activo en el catálogo.	Ver tipos de inmueble.

Solo en el alta obsoleta POST /v1/avaluos (no la uses; da de alta con POST /v1/avaluos/procesar), una institution o property_type que no existe en el catálogo responde 422 sin code, con el mensaje institution 'X' no existe en el catálogo o property_type 'X' no existe en el catálogo.

Evaluación

Código	HTTP	Cuándo	Cómo resolverlo
`DOCUMENTO_NO_LISTO`	`409`	El PDF todavía se está leyendo.	Espera a `document.estado: completed` y reintenta.
`DOCUMENTO_CON_ERRORES`	`409`	El PDF tiene errores que impiden evaluarlo.	Sube una versión corregida.

Certificado

Código	HTTP	Cuándo	Cómo resolverlo
`SIN_EVALUACION`	`409`	El avalúo aún no tiene evaluación.	La evaluación no arranca sola: cuando `document.puede_evaluar` sea `true`, lánzala con `POST /v1/avaluos/{folio}/evaluar` y certifica cuando `latest_evaluation.estado` sea `completed`.
`SIN_HASH`	`409`	No hay huella del documento que certificar.	Vuelve a subir el PDF; si persiste, repórtalo.
`EVALUACION_NO_COMPLETADA`	`409`	Faltan etapas por terminar.	Espera a `latest_evaluation.estado: completed`.
`CRITICOS_PENDIENTES`	`409`	Hay hallazgos críticos sin justificar.	Justifícalos o corrige el PDF.
`HALLAZGOS_PENDIENTES`	`409`	Hay hallazgos sin justificar, de cualquier severidad.	Justifícalos o corrige el PDF.

DOCUMENTO_NO_LISTO y DOCUMENTO_CON_ERRORES también pueden aparecer al certificar.

Dictamen

Código	HTTP	Cuándo	Cómo resolverlo
`MOTIVO_REQUERIDO`	`400`	Rechazo sin motivo o con menos de 10 caracteres.	Escribe el motivo del rechazo.
`YA_DICTAMINADO`	`409`	Ya hay un dictamen vigente.	Reábrelo antes de emitir otro.
`SIN_CERTIFICADO`	`409`	El avalúo no tiene certificado vigente.	El perito debe emitirlo.
`VERIFICACION_REQUERIDA`	`409`	Nunca se verificó el PDF contra el certificado.	Registra una verificación.
`VERIFICACION_FALLIDA`	`409`	La última verificación no dio `coincide`.	Verifica con el PDF correcto.
`VERIFICACION_DESACTUALIZADA`	`409`	El `verificacion_id` no es la última verificación, o el PDF cambió de versión.	Verifica de nuevo y usa el `verificacion_id` nuevo.
`SIN_DICTAMEN`	`409`	No hay dictamen vigente que reabrir.	Nada que hacer.

Catálogos

Código	HTTP	Cuándo	Cómo resolverlo
`CODIGO_DUPLICADO`	`409`	Ya existe una institución o tipo de inmueble con ese `codigo`.	Usa otro código o edita el existente.
`CLAVE_DUPLICADA`	`409`	Ya existe una institución o tipo de inmueble con esa `clave`.	Usa otra clave o edita el existente.
`REGLA_DUPLICADA`	`409`	El `codigo_regla` ya existe, aunque esté retirado.	Si está retirada, reactívala con `PATCH` y `activa: true`.
`KEY_DUPLICADA`	`409`	Ya existe una sección con esa `key`.	Usa otra `key`.
`INSTITUCION_NO_ENCONTRADA`	`404`	No existe la institución.	Revisa el `id`.
`TIPO_INMUEBLE_NO_ENCONTRADO`	`404`	No existe el tipo de inmueble.	Revisa el `id`.
`REGLA_NO_ENCONTRADA`	`404`	No existe la regla.	Revisa el código.
`SECCION_NO_ENCONTRADA`	`404`	No existe la sección.	Revisa el `id`.

Configuración

Código	HTTP	Cuándo	Cómo resolverlo
`CONFIGURACION_NO_EDITABLE`	`409`	El parámetro no se puede modificar.	Ninguna: es fijo.

Un valor fuera de rango o de otro tipo responde 422 sin code, con mensajes como no puede ser mayor que 50 o 'mercado.radio_km_default' espera un número.

Errores sin código

Estos no traen code: identifícalos por el status.

HTTP	Cuándo	Cómo resolverlo
`400`	El cuerpo o los parámetros no cumplen el contrato. `message` es un arreglo con cada problema.	Corrige los campos indicados.
`401`	Falta la API Key o no es válida.	Ver autenticación.
`403`	Faltan scopes, o la llave no es la que creó el avalúo (al eliminarlo o subir una versión nueva).	Pide los scopes o usa la llave correcta.
`404`	El folio o recurso no existe.	Revisa el identificador.
`413`	El cuerpo JSON supera 50 MB (pasa con un PDF de más de unos 37 MB, porque el base64 ocupa un tercio más).	Reduce el tamaño del PDF, por ejemplo bajando la resolución de las imágenes escaneadas.
`429`	Límite de peticiones superado.	Reintenta con backoff exponencial.