Manejo de errores
Códigos de error, estrategias de reintento y solución de problemas para la API del Gateway G-Force.
Manejo de errores
El Gateway de G-Force usa códigos de error basados en strings en el campo code de cada respuesta. Un código "200" significa éxito; cualquier otro es un error.
Códigos de error comunes
| Código | Significado | Acción |
|---|---|---|
200 | Éxito | Procesa la respuesta normalmente |
100 | Token de emisor inválido (solo ConsultRucDV) | Verifica credenciales del PAC |
101 | Token de emisor inválido | Credenciales del PAC incorrectas. Pide al usuario que reingrese Company/Token |
102 | Documento no encontrado / Duplicado | Depende del contexto (ver detalles por método abajo) |
109 | Error de validación | Parsea el campo message para ver qué campo falló |
201 | Error de procesamiento | Reintenta con backoff exponencial, luego alerta al usuario |
202 | DGI inalcanzable | La DGI está caída. Reintenta con backoff |
Códigos de error por método
SendDocument
| Código | Mensaje | Acción |
|---|---|---|
101 | Token de emisor inválido | Credenciales del PAC incorrectas |
102 | Documento duplicado | Factura ya enviada. Usa StatusDocument para verificar |
109 | Campo inválido / longitud / requerido | Parsea message para el nombre del campo y muéstralo al usuario |
201 | Error de procesamiento | Reintenta con backoff |
StatusDocument
| Código | Mensaje | Acción |
|---|---|---|
101 | Token de emisor inválido | Credenciales del PAC incorrectas |
102 | Documento no existe | Verifica numberDocumentFiscal y pointBillingFiscal |
109 | Error de validación | Parsea message para detalles del campo |
ConsultRucDV
Este método usa códigos de error distintos al resto de la API:
| Código | Mensaje | Acción |
|---|---|---|
100 | Token de emisor inválido | Nota: usa 100, no 101 |
101 | Error de certificado | Problema con el certificado del PAC. Reintenta o contacta a G-Force |
102 | Contribuyente no registrado | RUC no está en el sistema de la DGI. El usuario necesita registrarse primero |
201 | Error de procesamiento | Error genérico, reintenta |
202 | DGI inalcanzable | La DGI está caída, reintenta con backoff |
Errores de validación (código 109)
El código 109 cubre varios tipos de fallos de validación. El campo message contiene los detalles:
"Invalid field [campo]"-- valor incorrecto para el campo"Field [campo] length out of range"-- valor muy corto o muy largo"Field [campo] must be numeric"-- valor no numérico en un campo numérico"Field [campo] is required"-- campo requerido faltante"Field [campo] must not be included"-- el campo debió haberse omitido"In occurrence [n] of [campo]: ..."-- error en un elemento del array
Estrategia de reintento
Para errores transitorios (códigos 201 y 202), usa backoff exponencial:
Intento 1: espera 1s
Intento 2: espera 2s
Intento 3: espera 4s
Intento 4: espera 8s
Máximo de intentos: 4No reintentes para los códigos 101, 102 o 109 -- estos requieren acción del usuario o corrección en el código.
Consejos
- Registra los pares solicitud/respuesta durante la integración inicial. Redacta las credenciales pero conserva todo lo demás. Esto es crítico para debuggear comportamiento específico de cada PAC.
- El código
102tiene doble significado: enSendDocumentsignifica "duplicado", enStatusDocumentsignifica "no encontrado". Maneja ambos casos. - Campos opcionales: La documentación oficial dice omitirlos completamente. La colección de Postman los envía como strings vacíos y funciona. Si tienes errores de validación en producción, intenta omitir los campos en lugar de enviarlos vacíos.