Rate Limits and Usage Quotas for the SmartPyme API

The SmartPyme External API enforces hourly rate limits to ensure fair usage and platform stability. Your quota depends on whether you include date filters in your requests — adding fecha_inicio and fecha_fin doubles your allowance. Understanding how limits work helps you design integrations that stay well within quota.

Limits

Request type	Limit
Without date filters	1,000 requests/hour
With `fecha_inicio` + `fecha_fin`	2,000 requests/hour

Reset window

Rate limits operate on fixed hourly windows. The counter resets exactly at the top of each hour — for example, at 14:00, 15:00, 16:00, and so on. Requests made between 14:00 and 14:59 all count against the same window, and the counter starts fresh at 15:00 regardless of when you first made a request during that hour.

Rate limit headers

Every API response includes the following headers so you can track your current usage in real time:

Header	Description
`X-RateLimit-Limit`	Your current limit for this window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the limit resets

Checking your status

You can query your current rate limit status at any time by calling GET /system/rate-limit. This endpoint counts against your quota but returns a full picture of your usage for the current window.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.smartpyme.site/api/external/v1/system/rate-limit"

{
  "success": true,
  "data": {
    "requests_used": 25,
    "max_requests": 1000,
    "remaining_requests": 975,
    "reset_time": "2024-01-01T15:00:01Z",
    "window_minutes": 60,
    "limits": {
      "standard": 1000,
      "with_date_filters": 2000
    },
    "current_limit_type": "standard",
    "empresa_nombre": "Mi Empresa"
  }
}

Handling HTTP 429

When you exceed your rate limit, the API returns HTTP 429 Too Many Requests. To recover and avoid hitting the limit again, follow these recommendations:

Check the X-RateLimit-Reset header to determine exactly when your quota refreshes, then wait until that timestamp before retrying.
Add fecha_inicio and fecha_fin date filters to your requests — this doubles your hourly quota to 2,000 requests.
Use per_page=200 to fetch more records per request and reduce the total number of calls your integration makes.
Use summary endpoints (e.g. GET /sales/summary) to retrieve aggregate data instead of paginating through all individual records.

{
  "success": false,
  "error": "Rate limit exceeded",
  "code": 429
}

Always add fecha_inicio and fecha_fin to your requests — it doubles your hourly quota to 2,000 and often reduces the total number of requests needed by scoping results to a specific time range.

Overview

Endpoints

Rate Limits and Usage Quotas for the SmartPyme API

Limits

Reset window

Rate limit headers

Checking your status

Handling HTTP 429

​Limits

​Reset window

​Rate limit headers

​Checking your status

​Handling HTTP 429

Limits

Reset window

Rate limit headers

Checking your status

Handling HTTP 429