Skip to content

EMS API HTTP 429 Rate-Limit Issue and Configuration

1. Purpose

This document describes the cause, diagnosis, and recommended solution for the following EMS API error:

HTTP 429 Too Many Attempts
Illuminate\Http\Exceptions\ThrottleRequestsException

The issue was observed when EMS device clients such as:

  • PCS clients
  • Grid meter clients
  • Solar meter clients

send telemetry data to the Laravel API endpoint:

/api/insert-multi-device-data

2. Observed Error

The grid meter client was successfully reading Modbus data and storing it in the local database:

[2026-08-27 09:12:16] INFO: Inserted/updated 5 rows into grid_measurements
[✓] Inserted 5 gridMeter records

However, the API upload failed with:

[!][API] gridMeter: HTTP 429 pushing data:
{
    "message": "Too Many Attempts.",
    "exception": "Illuminate\\Http\\Exceptions\\ThrottleRequestsException"
}

This shows that:

  1. Modbus communication is working.
  2. Database insertion is working.
  3. The failure occurs only when sending the data to the Laravel API.

3. API Location

The API route was found inside the Docker container:

ems-frontend

Enter the container with:

docker exec -it ems-frontend bash

Application directory:

/var/www/html

4. API Endpoint

The EMS telemetry endpoint is defined in:

routes/api.php

The route was confirmed with:

grep -Rni "insert-multi-device-data" routes app 2>/dev/null

Result:

routes/api.php:55:
Route::post(
    'insert-multi-device-data',
    'Api\SensorDataInsertController@multiDeviceSensorData'
);

Therefore the EMS clients send data to:

POST /api/insert-multi-device-data

5. Root Cause

Laravel API throttling was found in:

app/Http/Kernel.php

Using:

grep -Rni "throttle" routes app/Providers app/Http 2>/dev/null

the following configuration was identified:

'throttle:60,1',

This means the Laravel API middleware allows approximately:

60 requests per minute

before returning:

HTTP 429 Too Many Attempts

The middleware implementation is registered as:

'throttle' => \Illuminate\Routing\Middleware\ThrottleRequests::class,

6. Why the EMS Exceeds the Limit

The EMS contains multiple devices that independently send telemetry.

For example:

PCS
Grid meters
Solar meters
Other EMS hardware

If a device sends data every 5 seconds:

60 / 5 = 12 requests/minute/device

For 36 devices:

36 × 12 = 432 requests/minute

Therefore the existing:

60 requests/minute

limit is too low for an EMS telemetry system.

Example:

Devices Upload Interval Approx. Requests/min
1 5 s 12
5 5 s 60
12 5 s 144
24 5 s 288
36 5 s 432

The current 60-request limit can therefore be reached with only approximately five devices uploading every five seconds.


For the EMS internal API, increase the Laravel API limit.

Current configuration:

'throttle:60,1',

Recommended configuration:

'throttle:1200,1',

This provides:

1200 requests/minute
≈ 20 requests/second

and gives additional capacity for future EMS hardware expansion.


8. Modification Procedure

Step 1 — Enter the Laravel container

docker exec -it ems-frontend bash

Step 2 — Check the existing throttle configuration

grep -n "throttle:" app/Http/Kernel.php

Expected existing configuration:

'throttle:60,1',

Step 3 — Change the API limit

Run:

sed -i "s/'throttle:60,1'/'throttle:1200,1'/" app/Http/Kernel.php

Step 4 — Verify the change

grep -n "throttle:" app/Http/Kernel.php

Expected result:

'throttle:1200,1',

Step 5 — Clear Laravel cache

php artisan optimize:clear

Step 6 — Exit the container

exit

Step 7 — Restart the container

docker restart ems-frontend

9. Verification

After restarting the container, monitor the EMS telemetry clients.

The expected successful message is similar to:

[✓][API] gridMeter: pushed reading(s)

The following error should no longer repeatedly appear:

HTTP 429 Too Many Attempts

The Laravel container can also be monitored with:

docker logs --tail 200 -f ems-frontend

The Modbus polling rate and HTTP API upload rate should be treated separately.

Recommended example:

Modbus polling      : 1 second
Local DB writing    : 5 seconds
EMS API upload      : 5–10 seconds

Fast Modbus polling is useful for local EMS control.

HTTP telemetry does not normally need to be transmitted for every Modbus polling cycle.

The EPCS105 PCS communication specification confirms that PCS communication uses standard Modbus read/write operations for real-time PCS measurements and control registers.


11. Client-Side HTTP 429 Handling

Increasing the Laravel limit solves the immediate server-side problem, but the Python EMS clients should also handle HTTP 429 responses correctly.

Recommended behavior:

if response.status_code == 429:
    retry_after = response.headers.get("Retry-After")

    try:
        wait_seconds = float(retry_after) if retry_after else 10.0
    except (TypeError, ValueError):
        wait_seconds = 10.0

    print(
        f"[!][API] HTTP 429 rate limited. "
        f"Retrying after {wait_seconds:.1f}s"
    )

    time.sleep(wait_seconds)
    return False

This prevents a device client from repeatedly sending requests while Laravel is already rate-limiting it.


For the current EMS architecture:

Laravel API throttle:
1200 requests/minute

Configuration:

'api' => [
    'throttle:1200,1',
    ...
],

Recommended telemetry architecture:

PCS              → EMS API
Grid Meter       → EMS API
Solar Meter      → EMS API
Other Sensors    → EMS API
                       │
                       ▼
          /api/insert-multi-device-data
                       │
                       ▼
               Laravel API
                       │
                 1200 req/min
                       │
                       ▼
                  EMS Database

13. Important Note

The change in:

app/Http/Kernel.php

applies to the Laravel API middleware group, not only to:

/api/insert-multi-device-data

Therefore other API endpoints using the same middleware group can also use the increased request limit.

For the current internal EMS environment this is acceptable.

For a future production architecture, a dedicated telemetry rate limiter can be created specifically for high-frequency EMS hardware endpoints while keeping lower limits on public or user-facing API endpoints.


14. Summary

Problem

HTTP 429 Too Many Attempts

Cause

Laravel API global throttle = 60 requests/minute

Location

ems-frontend
/var/www/html/app/Http/Kernel.php

Current

'throttle:60,1',

Recommended

'throttle:1200,1',

Apply

docker exec -it ems-frontend bash

sed -i "s/'throttle:60,1'/'throttle:1200,1'/" app/Http/Kernel.php

php artisan optimize:clear

exit

docker restart ems-frontend

This resolves the current EMS telemetry HTTP 429 problem while providing sufficient capacity for PCS, grid meter, solar meter, and additional EMS hardware data uploads.