Rate limits

Macrofy applies rate limits to ensure fair usage and platform stability.

Default limits

Name
Food search
Type
100 req/min
Description
GET /foods/search
Name
Barcode lookup
Type
100 req/min
Description
GET /foods/barcode/:upc
Name
Image scan (create)
Type
30 req/min
Description
POST /scan/image
Name
Image scan (poll)
Type
120 req/min
Description
GET /scan/image/:jobId

Limits are applied per API key.

Rate limit headers

Every response includes headers indicating your current rate limit status:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706918400

Name
X-RateLimit-Limit
Description
Maximum requests allowed in the current window.
Name
X-RateLimit-Remaining
Description
Requests remaining in the current window.
Name
X-RateLimit-Reset
Description
Unix timestamp when the window resets.

Handling rate limits

When you exceed the limit, the API returns 429 Too Many Requests:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "requestId": "req_abc123",
    "details": {
      "retryAfter": 30
    }
  }
}

Best practices

Respect Retry-After — Wait the specified seconds before retrying.
Implement exponential backoff — For transient errors, back off progressively.
Cache responses — Food search results can be cached client-side.
Batch requests — Where possible, reduce total request volume.

Increasing limits

Contact support@macrofy.com if you need higher limits for production use cases.