Manejo de errores

Cuando integras con la API de Debi, y especialmente al enviar una gran cantidad de requests, pueden ocurrir fallos temporales en la comunicación, como timeouts, errores HTTP 422 (errores de validación), errores HTTP 429 (Demasiadas solicitudes), o 502 (Bad Gateway). Para manejar estos casos de manera eficiente y garantizar la resiliencia de tu integración, puedes implementar un patrón de reintento que intente la solicitud nuevamente bajo ciertas condiciones.

Implementación de un Patrón de Reintento para Integraciones con la API de Debi

El siguiente ejemplo ilustra cómo hacerlo en PHP utilizando un patrón de reintento con manejo avanzado de errores.

Código de Ejemplo

// se recomienza maxRetries 10 y waitMilliseconds 5000
public Pago procesarPago(HttpRequest request, int maxRetries, int waitMilliseconds) {
    int attempts = 0;
    Pago pago = new Object(); // Inicializa el objeto, por ejemplo un pago Pago
    boolean success = false;

    while (attempts < maxRetries) {
        HttpResponse response = realizarPeticion(request); // Realiza la solicitud HTTP
        int statusCode = response.getStatusCode();

        if (statusCode == 200 || statusCode == 201) {
            // Éxito: procesar respuesta y terminar reintentos
            Map<String, Object> data = (Map<String, Object>) response.get("data");
            Utils.JSONToObject(data, pago, "Pago Response", pago);
            pago.sync_Retry__c = false;
            success = true;
            break;

        } else if (statusCode == 429 || statusCode == 499) {
            // Error transitorio: esperar y reintentar
            attempts++;
            esperar(waitMilliseconds);

        } else {
            // Otros errores: registrar el error y terminar
            pago.mensajeDeError = (String) response.get("message");
            pago.sync_Retry__c = false;
            break;
        }
    }

    if (!success) {
        // Si no hubo éxito tras todos los intentos, agregar a la lista de reintentos
        agregarAPagosPendientes(pago);
    }

    return pago;
}

Explicación del Código:

1. Reintentos

• Se recomienda reintentar especialmente si hay un gran número de request, por ejemplo podrías reintentar 10 veces.
• En el ejemlo, el sistema espera 5000 milisegundos (5 segundos).
• Los timeouts ocurren muy excepcionalmente. Cuando una solicitud tarda demasiado en recibir una respuesta, posiblemente es debido a problemas de red o carga en el servidor pero puedes considerar este escenario, y la estrategia es reintentar la petición.
• El encabezado Idempotency-Key garantiza que las solicitudes duplicadas no se procesen varias veces, incluso si se reintentan.
• en operaciones sensibles como pagos, este encabezado asegura que no se dupliquen transacciones si la misma solicitud es recibida varias veces por la API.

2. Caso de exceso de requests

• En caso de superar el número de requests permitidos para tu usuario, vas a recibir un error 429 "Too many requests" y deberías reintentar más tarde. Para esto también sirve el algoritmo sugerido.
• Normalmente los usuarios pueden realizar hasta 100 requests por minuto. Este parámetro puede ser modificado por nuestra área de soporte. Si necesitas configurar este parámetro puedes comunicarlo a soporte@debi.pro. Por ejemplo podrías solicitar una disminución de la cantidad de requests para testear que tu sistema sea capaz de reintentar exitosamente.

4. Manejo de Errores de Validación

• Los errores 422 (Unprocessable Entity) se analizan para identificar problemas en los datos enviados, como errores en el número de tarjeta o IBAN.
• En este caso, el código reestructura los mensajes de error para proporcionar un formato más comprensible antes de lanzar una excepción.
• Los errores 400 o 422 son definitivos. Puedes loguearlos en tu sistema, para tomar una decisión, por ejemplo, mostrarlos en el frontend a tu usuario.