Errors

This page lists the errors each Universal API endpoint can return: the path it comes from, the HTTP code, the errorCode (when there is one) and the message exactly as it arrives in the response.

How to read the tables

• Each message is transcribed verbatim, including those written in Spanish or containing typos. If you build logic on an error, compare by errorCode (or data.code in Risks) and not by the text.
• A message containing <campo> means the text changes depending on the field that failed.
• The Risks endpoints have their own catalog: Risks Error Codes.

---

Error response formats

Not every endpoint responds the same way. Identify the format by endpoint.

Format	Endpoints	Structure
Business with code	POST /candidate-requests	{ "isSuccess": true, "statusCode": 422, "message": "Unprocessable Entity.", "data": { "errorCode": "ERR012", "message": "..." } }
Field validation	POST /candidate-requests	{ "statusCode": 422, "errors": [ { "errorCode": "ERR002", "message": "..." } ] }
Standard	Authentication and permissions on every endpoint, 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": { } }

Behaviors worth knowing

• isSuccess does not indicate success in errors. In the business and Bulk formats it arrives as true even when the request failed. Decide by the HTTP code and by statusCode.
• POST /candidate-requests: the statusCode in the body is 422, but the HTTP response code is 400 (or 404 when a resource is not found).
• POST /signin: wrong credentials respond with HTTP 201 and "success": false. It does not return 401.
• GET /candidate-requests/{uuid}: if the uuid does not exist it responds with HTTP 200 and "statusCode": 404 inside the body.

---

Authentication and permissions

They apply to every endpoint that uses x-api-key or Authorization: Bearer. Standard format.

Path	HTTP	errorCode	message	Condition
All	401	—	Invalid credentials.	No credential was sent, or the API Key or token is not valid (nonexistent, disabled or expired).
All	403	—	Insufficient permissions.	The permissions of the role tied to the credential could not be retrieved.
All	403	—	Forbidden resource	The role is not allowed to use that endpoint.
All (with x-api-key)	429	—	Too many requests	The per-API-Key request limit was exceeded within the time window. Retry later.

note

Before reaching the service, the gateway may reject the request with its own 401 or 403. Those messages are defined by the gateway and are not part of this catalog.

---

POST /signin

Standard format for the 400s. Wrong credentials do not return an HTTP error code.

Path	HTTP	errorCode	message	Condition
POST /signin	201	—	El nombre de usuario o la contraseña son incorrectos. (with "success": false)	Nonexistent user, inactive user, wrong password, locked or disabled account. The cause is not distinguished.
POST /signin	201	—	Se requiere autenticación de múltiples factores. (with "success": false)	The account has a second factor enabled.
POST /signin	400	—	email must be an email	email missing or badly formatted.
POST /signin	400	—	password should not be empty / password must be a string	password missing, empty or not text.
POST /signin	400	—	property <campo> should not exist	The body includes a field that does not exist.
POST /signin	500	—	Internal server error	Internal error.

---

POST /candidate-requests

Also available as POST /services/candidate-requests (API Key). The type of every field is validated first (field validation format), then the business rules (business with code format).

Field validation

HTTP 400. The message is inside errors[].

Path	HTTP	errorCode	message	Condition
POST /candidate-requests	400	ERR002	Required fields are missin g to perform this query: byNationalId	byNationalId missing or not a boolean.
POST /candidate-requests	400	ERR002	Required fields are missing to perform this query: <campo>	package, taxClassification or clientId missing or not text.
POST /candidate-requests	400	ERR015	The email entered does not match the correct format.	email badly formatted.
POST /candidate-requests	400	ERR000	The date on which the consent was accepted is required.	consent.consentDate empty.
POST /candidate-requests	400	ERR000	The date on which the terms and conditions were accepted is required.	consent.termsAgreementDate empty.
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 badly formatted.
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 badly formatted.
POST /candidate-requests	400	ERR000	1 to 70 characters	streetAndNumber, delegationOrMunicipality, city or company outside 1 to 70 characters.
POST /candidate-requests	400	ERR000	Only alphanumeric characters are accepted	The same fields with disallowed characters.
POST /candidate-requests	400	ERR000	The postal code must contain exactly 5 digits	postalCode is not exactly 5 digits.
POST /candidate-requests	400	ERR000	resultNotificationUrl must be a URL address	resultNotificationUrl is not a URL.
POST /candidate-requests	400	ERR000	costCenter must be a number conforming to the specified constraints	costCenter is not numeric.
POST /candidate-requests	400	ERR000	<campo> must be a string / <campo> must be a boolean value / <campo> must be an object	Any other field with a type different from the expected one.

Business rules: legal entity (taxClassification: "PM")

Path	HTTP	errorCode	message	Condition
POST /candidate-requests	400	ERR019	businessName is required.	businessName is missing.
POST /candidate-requests	400	ERR019	corporateRegime is required.	The regime field is missing.
POST /candidate-requests	400	ERR019	registrationCountry must match a valid catalog entry.	registrationCountry is not in the wc-countries catalog.
POST /candidate-requests	400	ERR000	Validation error	regime is not in the tax regime catalog.

Business rules: individual (taxClassification: "PF")

Path	HTTP	errorCode	message	Condition
POST /candidate-requests	400	ERR019	taxClassification has an incorrect format	taxClassification other than PF and PM.
POST /candidate-requests	400	ERR002	The national ID does not have the correct format.	nationalId does not match the country format. With byNationalId: true.
POST /candidate-requests	400	ERR016	The national ID is required.	nationalId is missing. With byNationalId: true.
POST /candidate-requests	400	ERR007	name is required to complete the registration.	name is missing. With byNationalId: false.
POST /candidate-requests	400	ERR010	The field last name is required to complete the registration.	lastName is missing. With byNationalId: false.
POST /candidate-requests	400	ERR011	The field birthdate does not have the correct format.	birthDate missing, in a format other than DD/MM/YYYY, before 1900 or in the future.
POST /candidate-requests	400	ERR011	The sex field is required to complete the registration.	sex is missing.
POST /candidate-requests	400	ERR020	The sex field has an incorrect format.	sex other than H, M or X.
POST /candidate-requests	400	ERR012	The state field is required to complete the registration.	state is missing.
POST /candidate-requests	400	ERR021	The state field has an incorrect format.	state is not a valid state code.
POST /candidate-requests	400	—	the following fields are required or have incorrect formats: [name, lastName, secondLastName, birthDate, sex, state]	name or lastName contain disallowed characters.
POST /candidate-requests	400	ERR010	The candidate you are trying to register is not of legal age.	The candidate is under 18.
POST /candidate-requests	400	ERR012	The gender is invalid.	gender other than H or M.

User, client and package

Path	HTTP	errorCode	message	Condition
POST /candidate-requests	404	ERR017	User not found.	The user tied to the credential does not exist.
POST /candidate-requests	400	ERR017	Package is required.	package is empty.
POST /candidate-requests	404	ERR007	The package <id> with which the registration is being attempted does not exist.	The package does not exist.
POST /candidate-requests	404	ERR008	The client <id> with which the registration is being attempted does not exist.	The clientId does not exist.
POST /candidate-requests	404	ERR003	This package is not available to you.	The package is not assigned to your client.
POST /candidate-requests	404	—	Country not found	The client does not have the given country configured.
POST /candidate-requests	400	ERR002	This package only allows registration using a National ID.	The package does not allow registration by name and byNationalId: false was sent.

Fields required by the package

Path	HTTP	errorCode	message	Condition
POST /candidate-requests	400	ERR012	The <campo> field is required to complete the registration.	A field the package requires is missing.
POST /candidate-requests	400	ERR012	The nss field has an invalid format.	nss is not 11 digits.
POST /candidate-requests	400	ERR012	The rfc and curp do not match.	rfc and nationalId are not consistent.
POST /candidate-requests	400	ERR012	The RFC is required.	Package with Credit Report and no rfc.
POST /candidate-requests	400	ERR012	The candidate consent is required to complete the registration.	Package with Credit Report that requires consent.
POST /candidate-requests	400	ERR020	The PIN does not match the provided data.	The RFC year does not match digits 3 and 4 of consentNIP.
POST /candidate-requests	400	ERR015	The email address is required for this process.	The package requires interaction with the candidate and email is missing.
POST /candidate-requests	400	ERR012	The homeAddress are required.	Package with Credit Report that requires homeAddress.
POST /candidate-requests	400	ERR012	The workAddress are required.	hasWorkExperience is true and workAddress is missing.

Cost center

These errors arrive in the field validation format with the generic Validation error message (ERR000). The actual cause is in the last column.

Path	HTTP	errorCode	message	Cause
POST /candidate-requests	400	ERR000	Validation error	costCenter is mandatory for your client and was not sent.
POST /candidate-requests	400	ERR000	Validation error	costCenter was sent but your client does not use cost centers.
POST /candidate-requests	400	ERR000	Validation error	Your client has no cost centers configured, or the given center is disabled.
POST /candidate-requests	404	—	Cost center <id> not found	The cost center does not exist. Standard format.

---

GET /candidate-requests/{uuid}

Also available as GET /services/candidate-requests/{uuid} (API Key).

Path	HTTP	errorCode	message	Condition
GET /candidate-requests/{uuid}	200	—	candidate request not found (with "statusCode": 404 in the body)	The uuid does not exist.

---

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

Path	HTTP	errorCode	message	Condition
GET /candidate-requests/{uuid}/processes/{processId}	500	—	Failed to get process details: <detalle>	The Process detail could not be retrieved.

note

page and limit are not validated: a non-numeric value does not produce a 400 error.

---

POST /bulk-loading/upload

Bulk format. Only available with Authorization: Bearer.

Path	HTTP	errorCode	message	Condition
POST /bulk-loading/upload	400	—	Only CSV files are allowed	The file is not a CSV.
POST /bulk-loading/upload	400	—	File not found	The file form field is missing.
POST /bulk-loading/upload	400	—	Register type not found	registerType is missing.
POST /bulk-loading/upload	400	—	CSV malformed => <detalle>	The CSV cannot be read.
POST /bulk-loading/upload	400	—	File validation failed (with data.details.errors, for example national_id is required)	A required column is missing. Only the first record with an error is reported.
POST /bulk-loading/upload	401	—	User is not authorized	The user's role cannot perform bulk uploads.
POST /bulk-loading/upload	404	—	Client not found	The user's client does not exist.
POST /bulk-loading/upload	413	—	Standard server message	The file exceeds 5 MB.
POST /bulk-loading/upload	500	—	Internal Server Error	Internal error, or registerType other than byName and byNationalId.

---

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

Path	HTTP	errorCode	message	Condition
GET /bulk-loading/file/{uuid}/status	404	—	UUID not found	The uuid does not match any upload.
GET /bulk-loading/file/{uuid}/status	500	—	Internal Server Error	The link to the error file could not be generated.

---

Per-record errors in a bulk upload

These errors are not returned as an HTTP response. They are processed after the file is uploaded and end up in the error CSV file delivered in fileUrl by GET /bulk-loading/file/{uuid}/status, in the reasonFail column. They have no errorCode.

Origin	reasonFail	Condition
Package	Package not found	The package_id does not exist.
Package	Credit report process is not supported	The package includes Credit Report, which is not available in bulk upload.
Package	Email is required	The package requires interaction with the candidate and the email is missing.
Country	country_id is required / country_id is invalid	Missing, or not in the country catalog.
Data	birthDate is invalid	Date not in DD/MM/YYYY format, or nonexistent.
Data	sex must be "M" or "H"	Registration by name only.
Data	state is required / state must be in code. Ex: "TS" or "HG"	Registration by name only.
Data	National id incorrect syntax	Registration by identifier only.
Data	NSS is invalid	nss is not 11 digits.
Data	rfc is required / RFC is invalid	Package with SAT blacklists or Credit Report.
Data	personalReferences are required / personalReferences must be grater than 0	Package with Personal References.
Data	btrustProfile is invalid / btrustCategories are required / btrustCategories are invalid	Package with the Btrust Process.
Cost center	costCenter is required	The client uses cost centers and it is missing.
Cost center	costCenter is not allowed or required	costCenter was sent but the client does not use it.
Cost center	Cost center does not exist or is not visible	The center does not exist or is disabled.
Processing	Unexpected error processing the candidate	Internal error while processing the record.
Candidate registration	Could not save candidate in database, State not found, Could not fetch package and similar	Failure during registration after validation.

---

Risks

Risks format. The detail of each code, whether it is charged and whether it can be retried is in Risks Error Codes. This table shows which path each one belongs to.

Path	HTTP	data.code	message	Condition
POST /risks/legal-records/searches	400	INVALID_SEARCH_CRITERIA	El criterio de búsqueda no es válido (with data.reasons)	Incomplete or invalid search criteria.
POST /risks/legal-records/searches	400	IDENTITY_NOT_FOUND	La CURP no corresponde a una persona registrada	Search by nationalId for a well-formed CURP that does not exist.
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	Search by nationalId while the identity service is down.
GET /risks/legal-records/searches/{searchId}	404	SEARCH_NOT_FOUND	La búsqueda no existe o no pertenece al cliente	The searchId does not exist or belongs to another client.
GET /risks/legal-records/searches/{searchId}	410	SEARCH_EXPIRED	La búsqueda expiró; ejecuta una nueva búsqueda	More than 2 hours have passed since the search.
GET /risks/legal-records/searches/{searchId}/records/{uuid}	404	SEARCH_NOT_FOUND	La búsqueda no existe o no pertenece al cliente	The searchId does not exist or belongs to another client.
GET /risks/legal-records/searches/{searchId}/records/{uuid}	404	MATCH_NOT_FOUND	La coincidencia no pertenece a la búsqueda indicada	The uuid is not part of that search.
GET /risks/legal-records/searches/{searchId}/records/{uuid}	410	SEARCH_EXPIRED	La búsqueda expiró; ejecuta una nueva búsqueda	The search expired and the record had not been consulted before.
GET /risks/legal-records/searches/{searchId}/records/{uuid}	503	PROVIDER_UNAVAILABLE	La fuente de antecedentes legales no está disponible; reintenta en unos momentos	The source does not respond. If it carries data.unlockAlreadyCharged: true, the unlock was already charged and retrying does not charge again.
GET /risks/legal-records/searches/{searchId}/records/{uuid}/csv	404	SEARCH_NOT_FOUND / MATCH_NOT_FOUND	Same as in the detail	The searchId or the uuid do not exist.
GET /risks/legal-records/searches/{searchId}/records/{uuid}/csv	409	MATCH_NOT_UNLOCKED	La coincidencia no ha sido desbloqueada	The CSV was requested for a record whose detail has not been consulted.
GET /risks/legal-records/searches/{searchId}/records/{uuid}/csv	503	PROVIDER_UNAVAILABLE	La fuente de antecedentes legales no está disponible; reintenta en unos momentos	The source does not respond.
All /risks/legal-records/*	400	—	El usuario tiene acceso a varios clientes; indica clientId para atribuir el consumo	Your user has several clients and you did not send clientId.
All /risks/legal-records/*	403	—	No cuentas con acceso a este cliente	The clientId sent is not one of your clients.
All /risks/legal-records/*	400	—	<campo> debe tener el formato DD-MM-YYYY, property <campo> should not exist or other validation messages	Parameters or body with an invalid format.