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 |
INTERNAL_ERROR | 200 | Ocurrió un error inesperado | Guarda el transactionId y escribe a 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. 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). 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: "<nombre del campo>"). |
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. |
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 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 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.
