> ## Documentation Index > Fetch the complete documentation index at: https://docs.origoid.com/llms.txt > Use this file to discover all available pages before exploring further. # Errores > Tipos comunes de error y cómo manejarlos. OrigoID nunca devuelve errores opacos. Cada error incluye: * Un **código `type` estable** que no cambia entre versiones * Un **`message` humano** describiendo qué pasó * Una ruta accionable hacia la solución ## Tipos comunes de error | `type` | HTTP | Qué significa | Qué hacer | | --------------------- | ---- | -------------------------------------------- | --------------------------------------------------------------------------------------- | | `INVALID_REQUEST` | 200 | Tu body no pasó validación | Inspecciona `errors[]`, corrige los campos listados, reintenta | | `UNAUTHORIZED` | 401 | Falló autenticación | Verifica tu API key. Revisa tu IP allow-list. Si sospechas filtración, rota. | | `RATE_LIMIT_EXCEEDED` | 429 | Excediste tu rate limit | Implementa backoff exponencial. Considera upgrade de plan. | | `SERVICE_UNAVAILABLE` | 200 | Una fuente upstream está temporalmente caída | Retry con backoff. Verifica [status.origoid.com](https://status.origoid.com) | | `INTERNAL_ERROR` | 200 | Ocurrió un error inesperado | Guarda el `transactionId` y escribe a [support@origoid.com](mailto:support@origoid.com) | ## Códigos de resultado específicos por endpoint Cada endpoint puede devolver códigos `type` adicionales que representan resultados de negocio válidos (no errores per se). Por ejemplo: * Endpoints CURP pueden devolver `CURP_NOT_FOUND`, `CURP_APOCRYPHAL`, `CURP_DECEASED` * Endpoints SAT pueden devolver `CFDI_CANCELED`, `TAX_PROFILE_NOT_FOUND` * Endpoints Voter ID pueden devolver `INE_NOT_FOUND`, `INE_NOT_VALID` * Endpoints biométricos pueden devolver `FACE_MISMATCH`, `MASK_ATTACK` La lista completa de códigos `type` para cada endpoint está documentada en su página de la [referencia API](/es/api-reference). Maneja los resultados de negocio según tu lógica de dominio. ## Códigos de validación Cuando `type` es `INVALID_REQUEST`, el array `errors[]` lista los fallos a nivel campo (ver [ErrorDetail](/es/envelope#errordetail-entradas-de-errors)). Cada entrada tiene un `code` sobre el que puedes branchear. Estos códigos son **transversales** — pueden aparecer en cualquier endpoint cuando la validación correspondiente falla: | `code` | Cuándo aparece | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MALFORMED_JSON` | El body del request no es JSON válido. El `field` es `body`. | | `PAYLOAD_TOO_LARGE` | El body completo excede 28 MB (`field: "body"`) o un campo base64 de imagen/PDF excede 12 MB (`field: ""`). | | `MISSING_REQUIRED_FIELD` | Falta un campo requerido. | | `MISSING_DEPENDENT_FIELD` | Falta un campo que depende de otro requerido (ej. `cif` provisto sin `rfc`). | | `INVALID_TYPE` | Un campo tiene tipo primitivo equivocado (ej. número donde se espera string). | | `INVALID_FORMAT` | Un campo no cumple su pattern o formato (CURP, RFC, NSS, fechas ISO, base64, etc.). | | `INVALID_ENUM_VALUE` | El valor del campo no está en el enum permitido. Ver [Catálogos](/es/catalogs). | | `INVALID_LENGTH` | Un string es más corto o largo de lo permitido. | | `OUT_OF_RANGE` | Un valor numérico está fuera del rango permitido. | | `INVALID_ARRAY` | Un array tiene muy pocos/muchos elementos, o duplicados no permitidos. | | `UNKNOWN_FIELD` | El body contiene un campo que el endpoint no reconoce. | | `SCHEMA_MISMATCH` | El body no satisface una restricción `oneOf` / `anyOf` — específicamente, todas las alternativas se proveyeron cuando sólo una era permitida. Cuando algunas alternativas faltan, recibes `MISSING_REQUIRED_FIELD` por alternativa en su lugar. | | `INVALID_SCOPE` | El scope OAuth solicitado no está otorgado al API key. Devuelto por `/auth/token` cuando el caller pide scopes fuera de su grant. | | `INVALID_VALUE` | Un valor es inválido por razones no cubiertas arriba (fallback típico). | ### Códigos específicos de endpoint Algunos endpoints agregan códigos adicionales que capturan validación de dominio. Por ejemplo: * `INVALID_RFC_FORMAT` (`/mex/fiscal/v1/rfc-validations`, búsquedas SAT 69 / 69-B) * `NAME_TOO_SHORT`, `NAME_ONLY_STOPWORDS` (búsquedas SAT 69 / 69-B) * `QR_NOT_FOUND` (`/mex/fiscal/v1/csf-extractions`, `/mex/fiscal/v1/cfdi-validations`) * `IMAGE_UNREADABLE` (endpoints OCR) Consulta la página de cada operación en la [referencia API](/es/api-reference) para la lista completa. ### Cómo se agregan los errores Múltiples fallos de validación de campos en un mismo request pueden venir juntos en `errors[]`. El tamaño del array depende del tipo de validación que falló: * Los fallos de validación de estructura del request (campos requeridos faltantes, tipos incorrectos, patterns malos, mismatches de enum / length / range) se **agregan** — todas las violaciones de este tipo regresan en una sola respuesta. * Los fallos detectados por checks de dominio (ej. `INVALID_RFC_FORMAT`, `NAME_TOO_SHORT`, `QR_NOT_FOUND`) pueden devolver sólo el **primer** error encontrado, aunque otros campos también hubieran fallado. Siempre itera `errors[]` en lugar de asumir una sola entrada. Si tu código recibe un error, lo corrige y reenvía, la siguiente respuesta puede mostrar errores adicionales que estaban latentes. ## Reportar un problema Si encuentras un error inesperado, escribe a [support@origoid.com](mailto:support@origoid.com) con: * El `transactionId` de la respuesta * Breve descripción de qué intentabas hacer * El endpoint que llamaste No almacenamos request bodies ni response bodies, por lo que no podemos recuperar tu llamada automáticamente. Cuando reportes, incluye el `transactionId` y el path que llamaste, y trabajaremos contigo en los siguientes pasos.