Rate limits & errors

Rate limit

The public API allows 10 requests per minute per customer. The fixed window applies across all four device endpoints.

Successful responses include:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed in the current minute
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix epoch time in seconds when the window resets

When the limit is exceeded, the API returns 429 Too Many Requests and includes a Retry-After header.

{
  "message": "Rate limit exceeded: 10 requests per minute. Retry in 24s."
}

Use Retry-After, add jitter to retries, and cache device data where your application permits it.

Status codes

Status	Meaning	Recommended action
`200`	Request succeeded	Parse the JSON response
`400`	Required query input is missing or invalid	Correct the request; do not retry unchanged
`401`	`X-API-KEY` header is missing	Add the header; do not retry without credentials
`403`	API key is invalid or not authorized	Check the key or ask support to rotate it
`404`	Device, assigned device set, or telemetry was not found	Verify device ownership and data availability
`429`	Customer rate limit exceeded	Wait for `Retry-After`, then retry
`500`	Unexpected service error	Retry with exponential backoff; contact support if persistent

Retry example

async function getDevices(apiKey) {
  const response = await fetch('https://api.tamsys.app/p/devices/list', {
    headers: {
      'X-API-KEY': apiKey,
      Accept: 'application/json'
    }
  })

  if (response.status === 429) {
    const retryAfter = Number(response.headers.get('retry-after') ?? 60)
    throw new Error(`TAMsys rate limit reached; retry after ${retryAfter}s`)
  }

  if (!response.ok) {
    throw new Error(`TAMsys API returned ${response.status}`)
  }

  return response.json()
}