Rate Limits

Valora rate limits API traffic to protect service stability and keep access fair across integrations.

Default limits

Endpoint pages may document more specific limits when they differ.

Plan-based limits

Customer accounts may be assigned a plan with additional windows, such as hourly, daily, weekly, or monthly quotas. When multiple windows apply, every request must fit within all active windows.

For example, a plan can allow:

{
  "minute": 120,
  "hour": 5000,
  "day": 50000,
  "month": 1000000
}

If any one window is exhausted, the API returns 429 Too Many Requests until that window resets.

Check your current limits

Authenticated API token owners can check their current usage and reset times.

GET https://valora.spotahome.com/api/v1/tokens/limits
Authorization: Bearer {token}
Accept: application/json

Example response:

{
  "message": "Rate limits retrieved successfully",
  "rate_limits": {
    "audience": "customer",
    "plan": {
      "id": 12,
      "name": "Business",
      "slug": "business"
    },
    "limits": [
      {
        "window": "minute",
        "limit": 120,
        "used": 42,
        "remaining": 78,
        "resets_in_seconds": 31,
        "resets_at": "2026-05-03T22:30:00+02:00"
      }
    ]
  }
}

Rate limit response

When a client exceeds its limit, the API returns 429 Too Many Requests.

{
  "message": "Rate limit exceeded.",
  "rate_limit": {
    "window": "minute",
    "limit": 120,
    "used": 120,
    "remaining": 0,
    "resets_in_seconds": 31,
    "resets_at": "2026-05-03T22:30:00+02:00"
  }
}

Client behavior

• Back off when receiving 429.
• Retry after a delay instead of retrying immediately.
• Add jitter to automated retries so many jobs do not retry at the same time.
• Cache stable reference data where appropriate.
• Avoid polling more frequently than the workflow requires.

Suggested retry strategy

For automated integrations:

Stop retrying after repeated failures and surface the issue to an operator or monitoring system.