Rate Limits and Retries

The OpenAPI service applies rate limiting to protect stability and prevent excessive consumption by a single client. This page explains the rate limit rules and client retry guidance.

Rate Limit Rules

• When the server applies rate limiting, it returns 429 RATE_LIMITED
• A 429 response must include the Retry-After response header in seconds
• Retry-After must be a positive integer
• The exact quota and window depend on the service plan or deployment environment

Idempotency-Key

Idempotency-Key is the unique request key generated by the caller for one command request.

It is used to handle network timeouts or retry scenarios. If the client is not sure whether a command request has already been accepted by OpenAPI, it can retry the same request with the same Idempotency-Key to avoid creating a duplicate command.

Rules:

• Generate a new Idempotency-Key for every new command request
• Reuse the original Idempotency-Key when retrying the same command request
• Do not reuse the same Idempotency-Key for different devices, different relays, or different request bodies
• Idempotency-Key is not an access token and is not used for authentication

Client Retry Rules

• After receiving 429, the client should wait for the duration indicated by Retry-After before retrying
• After receiving 500 INTERNAL_ERROR, the client may retry with exponential backoff
• For side-effecting command endpoints, retries must reuse the same Idempotency-Key
• Clients should use bounded retries with jitter and must avoid tight retry loops
• Clients should not retry 400, 401, 403, 404, 409, or 422 without changing the request or credentials

Rate Limit Response Example

HTTP/1.1 429 Too Many Requests
Retry-After: 3
RateLimit: limit=1, remaining=0, reset=3

{
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "requestId": "req_001",
  "data": {
    "retryAfterSeconds": 3
  }
}

retryAfterSeconds carries the same value as the Retry-After response header, in seconds.