Errores

Esta página lista los errores que puede devolver cada endpoint de la API Universal: el path del que sale, el código HTTP, el errorCode (cuando existe) y el message tal como llega en la respuesta.

Cómo leer las tablas

• Los message están transcritos literalmente, incluidos los que están en inglés o tienen errores de redacción. Si construyes lógica sobre un error, compara por errorCode (o data.code en Risks) y no por el texto.
• Un message con <campo> indica que el texto cambia según el campo que falló.
• Los errores de los endpoints de Risks tienen su propio catálogo: Códigos de errores de Risks.

---

Formatos de respuesta de error

No todos los endpoints responden igual. Identifica el formato por el endpoint.

Formato	Endpoints	Estructura
Negocio con código	POST /candidate-requests	{ "isSuccess": true, "statusCode": 422, "message": "Unprocessable Entity.", "data": { "errorCode": "ERR012", "message": "..." } }
Validación de campos	POST /candidate-requests	{ "statusCode": 422, "errors": [ { "errorCode": "ERR002", "message": "..." } ] }
Estándar	Autenticación y permisos de todos los endpoints, POST /signin	{ "statusCode": 401, "message": "...", "error": "Unauthorized" }
Risks	/risks/legal-records/*	{ "isSuccess": false, "statusCode": 404, "message": "...", "data": { "code": "SEARCH_NOT_FOUND", "requestId": "..." } }
Bulk	/bulk-loading/*	{ "isSuccess": true, "statusCode": 400, "message": "...", "data": { } }

Comportamientos que conviene conocer

• isSuccess no indica éxito en los errores. En los formatos de negocio y Bulk llega en true aunque la petición haya fallado. Decide por el código HTTP y por statusCode.
• POST /candidate-requests: el statusCode del body es 422, pero el código HTTP de la respuesta es 400 (o 404 cuando no se encuentra un recurso).
• POST /signin: las credenciales incorrectas responden HTTP 201 con "success": false. No devuelve 401.
• GET /candidate-requests/{uuid}: si el uuid no existe responde HTTP 200 con "statusCode": 404 dentro del body.

---

Autenticación y permisos

Aplican a todos los endpoints que usan x-api-key o Authorization: Bearer. Formato estándar.

Path	HTTP	errorCode	message	Condición
Todos	401	—	Invalid credentials.	No se envió ninguna credencial, o la API Key o el token no son válidos (inexistente, deshabilitada o expirada).
Todos	403	—	Insufficient permissions.	No se pudieron obtener los permisos del rol asociado a la credencial.
Todos	403	—	Forbidden resource	El rol no tiene permiso para ese endpoint.
Todos (con x-api-key)	429	—	Too many requests	Se superó el límite de peticiones por API Key en la ventana de tiempo. Reintenta después.

nota

Antes de llegar al servicio, el gateway puede rechazar la petición con su propio 401 o 403. Esos mensajes los define el gateway y no están en este catálogo.

---

POST /signin

Formato estándar para los 400. Las credenciales incorrectas no devuelven un código de error HTTP.

Path	HTTP	errorCode	message	Condición
POST /signin	201	—	El nombre de usuario o la contraseña son incorrectos. (con "success": false)	Usuario inexistente, usuario inactivo, contraseña incorrecta, cuenta bloqueada o deshabilitada. No se distingue la causa.
POST /signin	201	—	Se requiere autenticación de múltiples factores. (con "success": false)	La cuenta tiene un segundo factor activo.
POST /signin	400	—	email must be an email	email ausente o con formato inválido.
POST /signin	400	—	password should not be empty / password must be a string	password ausente, vacío o no es texto.
POST /signin	400	—	property <campo> should not exist	El body incluye un campo que no existe.
POST /signin	500	—	Internal server error	Error interno.

---

POST /candidate-requests

Disponible también como POST /services/candidate-requests (API Key). Primero se valida el tipo de cada campo (formato de validación de campos) y después las reglas de negocio (formato de negocio con código).

Validación de campos

HTTP 400. El message va dentro de errors[].

Path	HTTP	errorCode	message	Condición
POST /candidate-requests	400	ERR002	Required fields are missin g to perform this query: byNationalId	byNationalId ausente o no es booleano.
POST /candidate-requests	400	ERR002	Required fields are missing to perform this query: <campo>	package, taxClassification o clientId ausentes o no son texto.
POST /candidate-requests	400	ERR015	The email entered does not match the correct format.	email con formato inválido.
POST /candidate-requests	400	ERR000	The date on which the consent was accepted is required.	consent.consentDate vacío.
POST /candidate-requests	400	ERR000	The date on which the terms and conditions were accepted is required.	consent.termsAgreementDate vacío.
POST /candidate-requests	400	ERR000	consentDate must be in the format dd/MM/yyyy HH:mm:ss (e.g., 01/05/1999 14:30:45)	consent.consentDate con formato inválido.
POST /candidate-requests	400	ERR000	termsAgreementDate must be in the format dd/MM/yyyy HH:mm:ss (e.g., 01/05/1999 14:30:45)	consent.termsAgreementDate con formato inválido.
POST /candidate-requests	400	ERR000	1 to 70 characters	streetAndNumber, delegationOrMunicipality, city o company fuera de 1 a 70 caracteres.
POST /candidate-requests	400	ERR000	Only alphanumeric characters are accepted	Esos mismos campos con caracteres no permitidos.
POST /candidate-requests	400	ERR000	The postal code must contain exactly 5 digits	postalCode no tiene exactamente 5 dígitos.
POST /candidate-requests	400	ERR000	resultNotificationUrl must be a URL address	resultNotificationUrl no es una URL.
POST /candidate-requests	400	ERR000	costCenter must be a number conforming to the specified constraints	costCenter no es numérico.
POST /candidate-requests	400	ERR000	<campo> must be a string / <campo> must be a boolean value / <campo> must be an object	Cualquier otro campo con un tipo distinto al esperado.

Reglas de negocio: persona moral (taxClassification: "PM")

Path	HTTP	errorCode	message	Condición
POST /candidate-requests	400	ERR019	businessName is required.	Falta businessName.
POST /candidate-requests	400	ERR019	corporateRegime is required.	Falta el campo regime.
POST /candidate-requests	400	ERR019	registrationCountry must match a valid catalog entry.	registrationCountry no está en el catálogo wc-countries.
POST /candidate-requests	400	ERR000	Validation error	regime no está en el catálogo de regímenes fiscales.

Reglas de negocio: persona física (taxClassification: "PF")

Path	HTTP	errorCode	message	Condición
POST /candidate-requests	400	ERR019	taxClassification has an incorrect format	taxClassification distinto de PF y PM.
POST /candidate-requests	400	ERR002	The national ID does not have the correct format.	nationalId no cumple el formato del país. Con byNationalId: true.
POST /candidate-requests	400	ERR016	The national ID is required.	Falta nationalId. Con byNationalId: true.
POST /candidate-requests	400	ERR007	name is required to complete the registration.	Falta name. Con byNationalId: false.
POST /candidate-requests	400	ERR010	The field last name is required to complete the registration.	Falta lastName. Con byNationalId: false.
POST /candidate-requests	400	ERR011	The field birthdate does not have the correct format.	birthDate ausente, con formato distinto de DD/MM/YYYY, anterior a 1900 o futura.
POST /candidate-requests	400	ERR011	The sex field is required to complete the registration.	Falta sex.
POST /candidate-requests	400	ERR020	The sex field has an incorrect format.	sex distinto de H, M o X.
POST /candidate-requests	400	ERR012	The state field is required to complete the registration.	Falta state.
POST /candidate-requests	400	ERR021	The state field has an incorrect format.	state no es una clave de estado válida.
POST /candidate-requests	400	—	the following fields are required or have incorrect formats: [name, lastName, secondLastName, birthDate, sex, state]	name o lastName contienen caracteres no permitidos.
POST /candidate-requests	400	ERR010	The candidate you are trying to register is not of legal age.	El candidato es menor de 18 años.
POST /candidate-requests	400	ERR012	The gender is invalid.	gender distinto de H o M.

Usuario, cliente y paquete

Path	HTTP	errorCode	message	Condición
POST /candidate-requests	404	ERR017	User not found.	El usuario asociado a la credencial no existe.
POST /candidate-requests	400	ERR017	Package is required.	package viene vacío.
POST /candidate-requests	404	ERR007	The package <id> with which the registration is being attempted does not exist.	El package no existe.
POST /candidate-requests	404	ERR008	The client <id> with which the registration is being attempted does not exist.	El clientId no existe.
POST /candidate-requests	404	ERR003	This package is not available to you.	El paquete no está asignado a tu cliente.
POST /candidate-requests	404	—	Country not found	El cliente no tiene configurado el país indicado.
POST /candidate-requests	400	ERR002	This package only allows registration using a National ID.	El paquete no admite registro por nombre y se envió byNationalId: false.

Campos requeridos por el paquete

Path	HTTP	errorCode	message	Condición
POST /candidate-requests	400	ERR012	The <campo> field is required to complete the registration.	Falta un campo que el paquete exige.
POST /candidate-requests	400	ERR012	The nss field has an invalid format.	nss no tiene 11 dígitos.
POST /candidate-requests	400	ERR012	The rfc and curp do not match.	rfc y nationalId no son consistentes.
POST /candidate-requests	400	ERR012	The RFC is required.	Paquete con Reporte de Crédito y sin rfc.
POST /candidate-requests	400	ERR012	The candidate consent is required to complete the registration.	Paquete con Reporte de Crédito que exige consent.
POST /candidate-requests	400	ERR020	The PIN does not match the provided data.	El año del RFC no coincide con los dígitos 3 y 4 de consentNIP.
POST /candidate-requests	400	ERR015	The email address is required for this process.	El paquete requiere interacción con el candidato y falta email.
POST /candidate-requests	400	ERR012	The homeAddress are required.	Paquete con Reporte de Crédito que exige homeAddress.
POST /candidate-requests	400	ERR012	The workAddress are required.	hasWorkExperience es true y falta workAddress.

Centro de costos

Estos errores llegan con el formato de validación de campos y el message genérico Validation error (ERR000). La causa real está en la última columna.

Path	HTTP	errorCode	message	Causa
POST /candidate-requests	400	ERR000	Validation error	costCenter es obligatorio para tu cliente y no se envió.
POST /candidate-requests	400	ERR000	Validation error	Se envió costCenter pero tu cliente no usa centros de costo.
POST /candidate-requests	400	ERR000	Validation error	Tu cliente no tiene centros de costo configurados, o el centro indicado está deshabilitado.
POST /candidate-requests	404	—	Cost center <id> not found	El centro de costo no existe. Formato estándar.

---

GET /candidate-requests/{uuid}

Disponible también como GET /services/candidate-requests/{uuid} (API Key).

Path	HTTP	errorCode	message	Condición
GET /candidate-requests/{uuid}	200	—	candidate request not found (con "statusCode": 404 en el body)	El uuid no existe.

---

GET /candidate-requests/{uuid}/processes/{processId}

Path	HTTP	errorCode	message	Condición
GET /candidate-requests/{uuid}/processes/{processId}	500	—	Failed to get process details: <detalle>	No se pudo obtener el detalle del Process.

nota

page y limit no se validan: un valor no numérico no produce un error 400.

---

POST /bulk-loading/upload

Formato Bulk. Solo disponible con Authorization: Bearer.

Path	HTTP	errorCode	message	Condición
POST /bulk-loading/upload	400	—	Only CSV files are allowed	El archivo no es CSV.
POST /bulk-loading/upload	400	—	File not found	Falta el campo file del formulario.
POST /bulk-loading/upload	400	—	Register type not found	Falta registerType.
POST /bulk-loading/upload	400	—	CSV malformed => <detalle>	El CSV no se puede leer.
POST /bulk-loading/upload	400	—	File validation failed (con data.details.errors, por ejemplo national_id is required)	Falta una columna requerida. Se reporta únicamente el primer registro con error.
POST /bulk-loading/upload	401	—	User is not authorized	El rol del usuario no puede hacer cargas masivas.
POST /bulk-loading/upload	404	—	Client not found	El cliente del usuario no existe.
POST /bulk-loading/upload	413	—	Mensaje estándar del servidor	El archivo supera 5 MB.
POST /bulk-loading/upload	500	—	Internal Server Error	Error interno, o registerType distinto de byName y byNationalId.

---

GET /bulk-loading/file/{uuid}/status

Path	HTTP	errorCode	message	Condición
GET /bulk-loading/file/{uuid}/status	404	—	UUID not found	El uuid no corresponde a ninguna carga.
GET /bulk-loading/file/{uuid}/status	500	—	Internal Server Error	No se pudo generar el enlace al archivo de errores.

---

Errores por registro de una carga masiva

Estos errores no se devuelven como respuesta HTTP. Se procesan después de subir el archivo y quedan en el archivo CSV de errores que entrega fileUrl en GET /bulk-loading/file/{uuid}/status, en la columna reasonFail. No tienen errorCode.

Origen	reasonFail	Condición
Paquete	Package not found	El package_id no existe.
Paquete	Credit report process is not supported	El paquete incluye Reporte de Crédito, que no está disponible en carga masiva.
Paquete	Email is required	El paquete requiere interacción con el candidato y falta el correo.
País	country_id is required / country_id is invalid	Falta o no está en el catálogo de países.
Datos	birthDate is invalid	Fecha distinta de DD/MM/YYYY o inexistente.
Datos	sex must be "M" or "H"	Solo en registro por nombre.
Datos	state is required / state must be in code. Ex: "TS" or "HG"	Solo en registro por nombre.
Datos	National id incorrect syntax	Solo en registro por identificador.
Datos	NSS is invalid	nss no tiene 11 dígitos.
Datos	rfc is required / RFC is invalid	Paquete con lista negra del SAT o Reporte de Crédito.
Datos	personalReferences are required / personalReferences must be grater than 0	Paquete con Referencias Personales.
Datos	btrustProfile is invalid / btrustCategories are required / btrustCategories are invalid	Paquete con el Process Btrust.
Centro de costos	costCenter is required	El cliente usa centros de costo y falta.
Centro de costos	costCenter is not allowed or required	Se envió costCenter pero el cliente no lo usa.
Centro de costos	Cost center does not exist or is not visible	El centro no existe o está deshabilitado.
Procesamiento	Unexpected error processing the candidate	Error interno al procesar el registro.
Registro del candidato	Could not save candidate in database, State not found, Could not fetch package y similares	Falla durante el registro posterior a la validación.

---

Risks

Formato Risks. El detalle de cada código, si se cobra y si se puede reintentar está en Códigos de errores de Risks. Aquí se muestra a qué path corresponde cada uno.

Path	HTTP	data.code	message	Condición
POST /risks/legal-records/searches	400	INVALID_SEARCH_CRITERIA	El criterio de búsqueda no es válido (con data.reasons)	Criterios de búsqueda incompletos o inválidos.
POST /risks/legal-records/searches	400	IDENTITY_NOT_FOUND	La CURP no corresponde a una persona registrada	Búsqueda por nationalId de una CURP bien formada que no existe.
POST /risks/legal-records/searches	503	PROVIDER_UNAVAILABLE	El servicio de identidad no está disponible, así que no se pudo resolver la CURP; reintenta en unos momentos	Búsqueda por nationalId con el servicio de identidad caído.
GET /risks/legal-records/searches/{searchId}	404	SEARCH_NOT_FOUND	La búsqueda no existe o no pertenece al cliente	El searchId no existe o es de otro cliente.
GET /risks/legal-records/searches/{searchId}	410	SEARCH_EXPIRED	La búsqueda expiró; ejecuta una nueva búsqueda	Pasaron más de 2 horas desde la búsqueda.
GET /risks/legal-records/searches/{searchId}/records/{uuid}	404	SEARCH_NOT_FOUND	La búsqueda no existe o no pertenece al cliente	El searchId no existe o es de otro cliente.
GET /risks/legal-records/searches/{searchId}/records/{uuid}	404	MATCH_NOT_FOUND	La coincidencia no pertenece a la búsqueda indicada	El uuid no está en esa búsqueda.
GET /risks/legal-records/searches/{searchId}/records/{uuid}	410	SEARCH_EXPIRED	La búsqueda expiró; ejecuta una nueva búsqueda	La búsqueda expiró y el registro no se había consultado antes.
GET /risks/legal-records/searches/{searchId}/records/{uuid}	503	PROVIDER_UNAVAILABLE	La fuente de antecedentes legales no está disponible; reintenta en unos momentos	La fuente no responde. Si trae data.unlockAlreadyCharged: true, el desbloqueo ya se cobró y reintentar no vuelve a cobrar.
GET /risks/legal-records/searches/{searchId}/records/{uuid}/csv	404	SEARCH_NOT_FOUND / MATCH_NOT_FOUND	Igual que en el detalle	El searchId o el uuid no existen.
GET /risks/legal-records/searches/{searchId}/records/{uuid}/csv	409	MATCH_NOT_UNLOCKED	La coincidencia no ha sido desbloqueada	Se pidió el CSV de un registro cuyo detalle no se ha consultado.
GET /risks/legal-records/searches/{searchId}/records/{uuid}/csv	503	PROVIDER_UNAVAILABLE	La fuente de antecedentes legales no está disponible; reintenta en unos momentos	La fuente no responde.
Todos los de /risks/legal-records/*	400	—	El usuario tiene acceso a varios clientes; indica clientId para atribuir el consumo	Tu usuario tiene varios clientes y no enviaste clientId.
Todos los de /risks/legal-records/*	403	—	No cuentas con acceso a este cliente	El clientId enviado no es uno de tus clientes.
Todos los de /risks/legal-records/*	400	—	<campo> debe tener el formato DD-MM-YYYY, property <campo> should not exist u otros mensajes de validación	Parámetros o body con formato inválido.