Referencia · 08

Errores

Todo error responde con un código HTTP y un cuerpo con forma fija:

{ "codigo": "consentimiento_faltante", "mensaje": "la peticion no trae el objeto de consentimiento otorgado" }

Programa contra codigo. Es estable; el mensaje es informativo y puede cambiar de redacción.
El mensaje nunca repite datos de tu petición (ni la CURP ni tus identificadores).
Una petición rechazada no crea verificación ni cobra.

Tabla de códigos

HTTP	Código	Significado	Qué hacer	¿Reintentar?
`400`	`campo_desconocido`	El cuerpo trae un campo que el esquema no declara. El esquema es cerrado.	Envia solo los campos documentados en la referencia; no agregues datos adicionales del solicitante.	No
`400`	`curp_invalida`	La CURP no cumple la forma oficial del registro nacional de poblacion.	Pide al solicitante que confirme su CURP (18 caracteres) y vuelve a intentar con un solicitud_id nuevo.	No
`400`	`idempotency_key_ausente`	Falta el encabezado Idempotency-Key en POST /v1/verificaciones.	Envia Idempotency-Key con el mismo valor que solicitud_id. El canal MCP lo hace por ti.	No
`400`	`peticion_invalida`	La peticion no tiene la forma del contrato, o sus insumos no pueden procesarse.	Valida el cuerpo contra la referencia. Usa identificadores opacos: solicitud_id y webhook_url no deben describir a la persona (salud, edad, estado civil, empleo, situacion familiar o migratoria, etc.).	No
`400`	`vocabulario_no_permitido`	Un campo que el canal te devuelve (por ejemplo solicitud_id o webhook_url) usa una palabra que el canal no emite.	Usa identificadores opacos (por ejemplo un UUID) en solicitud_id y una ruta neutra en webhook_url.	No
`401`	`llave_ausente`	No llego el encabezado Authorization con una llave en esquema Bearer.	Envia Authorization: Bearer <tu llave de socio>. En el canal MCP, configura ese encabezado en tu cliente.	No
`401`	`llave_invalida`	La llave no corresponde a ningun socio activo.	Revisa que la llave este completa y vigente, y que apunte al entorno correcto (sandbox o produccion). Si la rotaste, actualizala en tu cliente.	No
`402`	`cobro_no_verificado`	Modo connect: el PaymentIntent que respalda la verificacion no esta confirmado (succeeded), no es en MXN, no cubre el precio de tu plan o ya respaldo otra verificacion. No se ejecuto ni se cobro.	Confirma en tu Stripe que el cobro se completo en MXN por al menos el precio de tu plan y envia un payment_intent_id que no hayas usado antes, con un solicitud_id nuevo. Si el pago esta en orden, reintenta mas tarde con el mismo solicitud_id y el mismo payment_intent_id: la verificacion con Stripe pudo no completarse.	No
`402`	`consumo_agotado`	El saldo prepagado no alcanza para una verificacion mas. No se ejecuto ni se cobro.	Consulta GET /v1/cuenta/consumo y recarga saldo con tu contacto comercial antes de reintentar.	No
`404`	`verificacion_no_encontrada`	No hay una verificacion con ese identificador en el alcance de tu llave.	Revisa el verificacion_id (no el solicitud_id). Cada llave solo ve sus propias verificaciones.	No
`409`	`conflicto_idempotencia`	Esa Idempotency-Key ya se uso con un cuerpo distinto.	Si es la misma solicitud, reenvia exactamente el mismo cuerpo. Si es una solicitud nueva, usa un solicitud_id nuevo.	No
`413`	`cuerpo_demasiado_grande`	El cuerpo excede el tamano que el canal admite (64 KB).	Reduce el cuerpo; una verificacion por Ruta CURP ocupa muy poco.	No
`422`	`consentimiento_faltante`	La peticion no trae el objeto de consentimiento otorgado. No se crea verificacion ni se cobra.	Obten el consentimiento expreso del solicitante y envia consentimiento con otorgado=true, otorgado_en, version_aviso y evidencia_id.	No
`429`	`limite_excedido`	La llave excedio las peticiones por minuto que permite tu plan (o el cupo mensual, si tu plan lo tiene). No se ejecuto ni se cobro.	Espera y reintenta con backoff exponencial y jitter; respeta Retry-After si viene. En POST reutiliza el mismo solicitud_id.	Sí
`500`	`error_interno`	El canal no pudo completar la peticion.	Reintenta con backoff. En POST reutiliza el mismo solicitud_id: la idempotencia evita duplicados y cobros dobles.	Sí
`500`	`respuesta_retenida`	El canal retuvo su propia respuesta porque no paso su control de salida.	Reintenta mas tarde con el mismo solicitud_id; si persiste, reporta el verificacion_id a soporte.	Sí
`501`	`ruta_no_disponible`	La ruta con documento (INE) esta reservada y aun no se atiende.	Usa la Ruta CURP: no envies el objeto documento.	No
`503`	`base_no_alcanzable`	El canal esta arriba pero no alcanza su base de datos.	Reintenta en unos minutos con backoff; revisa GET /_salud.	Sí

Los códigos provienen del esquema RespuestaDeError de openapi.yaml; el build del portal falla si alguno queda sin documentar.

¿Por qué `peticion_invalida` no dice más?

Cuando la petición trae insumos que el canal no puede procesar —por ejemplo, identificadores que describen motivos protegidos de la persona— la respuesta es deliberadamente genérica. Usa identificadores opacos (UUID) en solicitud_id, propiedad_id y en la ruta de webhook_url.

Estrategia de reintento

Reintenta ante errores de red, 500, 503 y 429, con backoff exponencial y jitter. En POST usa el mismo solicitud_id.
No reintentes los demás 4xx sin corregir la causa.

Errores

Tabla de códigos

¿Por qué peticion_invalida no dice más?

Estrategia de reintento

¿Por qué `peticion_invalida` no dice más?