Rate limits, headers, and retry strategies

Header	Description
`X-RateLimit-Limit`	Maximum requests per window (100)
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp (ms) when the window resets
`Retry-After`	Seconds until reset (only on 429 responses)

Header

Description

X-RateLimit-Limit

Maximum requests per window (100)

X-RateLimit-Remaining

Requests remaining in current window

X-RateLimit-Reset

Unix timestamp (ms) when the window resets

Retry-After

Seconds until reset (only on 429 responses)

When You Hit the Limit

You’ll receive a 429 response:

{
  "error": {
    "type": "https://api.yoshi.ai/errors/rate-limited",
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 45 seconds.",
    "display_message": "Please wait a moment and try again.",
    "param": null,
    "retry_after": 45
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-10T12:00:00Z"
  }
}

Best Practices

Respect the Retry-After header

When you receive a 429, wait the number of seconds specified in retry_after before retrying. Don’t retry immediately.

Use exponential backoff

For retries on server errors (5xx), use exponential backoff: wait 1s, then 2s, then 4s, etc.

Cache responses where appropriate

Account data and scores don’t change every second. Cache responses for a reasonable duration to reduce API calls.

Use pagination efficiently

Fetch the data you need with appropriate limit values. The default is 50, max is 100.

If you need higher rate limits for your use case, contact support.

Rate limits, headers, and retry strategies

Limits

Response Headers

When You Hit the Limit

Best Practices

​Limits

​Response Headers

​When You Hit the Limit

​Best Practices

Limits

Response Headers

When You Hit the Limit

Best Practices