We enforce per-endpoint rate limits on a rolling 60‑second window to protect platform stability.
  • POST /v2/medias (upload): 10 requests / minute
  • GET /v2/medias/{media_uid}/file (download): 60 requests / minute
  • GET /v2/medias/{media_uid}/metadata (status): 120 requests / minute
  • X-RateLimit-Limit: Configured max requests for the endpoint within the window
  • X-RateLimit-Remaining: Requests remaining in the current 60‑second window
  • X-RateLimit-Used: Requests already used in the current window
  • X-RateLimit-Window: Window duration in seconds (e.g., 60)

​
Example

# Check metadata while inspecting headers
curl -i -sS \
  -H "X-API-Key: $AICOUSTICS_API_KEY" \
  "https://api.ai-coustics.io/v2/medias/$MEDIA_UID/metadata"

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Used: 2
X-RateLimit-Window: 60
Content-Type: application/json

{ "uid": "...", "enhancement_status": "COMPLETED", ... }
When the limit is exceeded, the server returns 429: 
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Used: 120
X-RateLimit-Window: 60
Content-Type: application/json

{ "detail": "Rate limit exceeded for this operation" }

​
Best practices

  • Poll smartly: For metadata, start at 3–5s intervals and back off to 5–10s for long jobs.
  • Fan‑out responsibly: Batch uploads to stay within 10/min on POST /v2/medias.
  • Handle 429: Implement exponential backoff with jitter, then retry when X-RateLimit-Remaining > 0.
  • Cache status: Avoid redundant metadata calls if your app already knows the last state.