Errores

Los mismos códigos en toda la API. Person Search, la consulta por fuente y las validaciones comparten el formato de error y el significado de cada código; lo único que cambia es qué lo dispara.

El cuerpo sigue la forma de Nest:

{ "statusCode": 400, "message": "…", "error": "Bad Request" }

message puede ser un string o un array de strings (validación).

Códigos

HTTP	Significado	Ejemplos por superficie
200	Ejecutado (puede ser total o parcial — ver partial).	También los veredictos negativos: email INVALID_SYNTAX, teléfono PROVIDER_ERROR.
400	El request no pudo ejecutarse.	Sin claves; entityType incompatible; fuente sin sus claves obligatorias; sobre mal formado.
401	API Key ausente o inválida.	Igual en todas.
403	Scopes insuficientes (ALL_OF).	Falta person_search:advanced; falta provider:bcra; falta utils:phone:hlr.
404	Recurso inexistente o no expuesto.	Search Model desconocido; slug de fuente desconocido.
429	Rate-limit o cuota (ver abajo).	Igual en todas.

"No pude ejecutar" ≠ "no encontré"

Un 400 significa que la consulta no se pudo correr. Una consulta válida que no encuentra nada devuelve 200 con subjects: []. La API nunca colapsa las dos cosas.

Ejemplos

400 — sin claves

{ "message": ["Se requiere al menos una clave de búsqueda (cuit/dni/name/birthDate)"], "error": "Bad Request", "statusCode": 400 }

400 — la fuente exige una clave que no enviaste

{ "message": "Ninguna fuente de descubrimiento del modelo puede ejecutarse con las claves provistas [NAME]. Requisitos mínimos por fuente: BCRA(CUIT)", "error": "Bad Request", "statusCode": 400 }

401 — sin key

{ "statusCode": 401, "message": "API Key requerida", "error": "Unauthorized" }

403 — falta scope

{ "statusCode": 403, "message": "Scopes insuficientes: person_search:advanced", "error": "Forbidden" }

404 — modelo o fuente inexistente

{ "message": "Search Model \"NOPE\" inexistente", "error": "Not Found", "statusCode": 404 }

{ "message": "Fuente \"nope\" inexistente o no disponible", "error": "Not Found", "statusCode": 404 }

Los 404 no revelan el catálogo interno: un recurso que existe pero no está expuesto responde igual que uno que no existe.

429 — dos casos distintos

No hay cabecera Retry-After

La pista de reintento viaja en el cuerpo (retryAfterMs), no en una cabecera HTTP.

Rate-limit (ventana por minuto) — incluye retryAfterMs (ms hasta el fin de la ventana):

{ "statusCode": 429, "message": "Rate limit excedido", "retryAfterMs": 4200 }

Cuota (diaria/mensual por key + producto) — sin pista de retry:

{ "statusCode": 429, "message": "Cuota diaria excedida (DAILY, límite 1000)" }

Parcialidad

partial: true indica que el resultado es utilizable pero incompleto porque una fuente que se ejecutó falló o se pasó de tiempo (típicamente una fuente LIVE). Las fuentes excluidas por permisos no marcan partial: simplemente no aparecen.

Ver Límites y facturación para los valores y el modelo de cobro.