clearlydefined / clearlydefined/service
GET /definitions?pattern= returns 503 under moderate concurrency despite rate limit not being reached
- Dominant language
- TypeScript
- Stars
- 51
- Forks
- 46
- PR merge metrics
- No merged PRs in 30d
Description
We're a downstream consumer of the ClearlyDefined API using the **GET /definitions?pattern=&minDescribedScore=80** endpoint to look up component definitions. During normal operation, our service sends 20–100 concurrent GET requests to this endpoint (one per component alias in a single search). We're intermittently seeing HTTP 503 responses on a significant portion of these requests, despite being well within the documented rate limit.
**Observed Behavior**
When sending 100 concurrent GET requests to [/definitions]:
- 25–68% of requests return HTTP 503 with body: [{"error":{"code":"503","message":"An error has occurred","innererror":{}}}]
- Rate limit headers on the 503 responses confirm budget is untouched:
Ratelimit-Policy: 2000;w=60
Ratelimit-Limit: 2000
Ratelimit-Remaining: 1986
Ratelimit-Reset: 60
- Successful requests complete in 0.1–1.1s
- Failed requests take 0.5–16s before returning 503 (sometimes up to 45–110s returning 502)
- The issue is intermittent - the same batch of requests succeeds 100% during healthy windows and fails 25-68% during degradation windows
- Zero HTTP 429 (rate limit) responses observed across hundreds of test requests
**Response Details (captured from a 503)
Headers:**
Server: cloudflare
CF-RAY: a1baca8f6cccc501-SJC
Cf-Cache-Status: BYPASS
Ratelimit-Policy: 2000;w=60
Ratelimit-Limit: 2000
Ratelimit-Remaining: 1986
Ratelimit-Reset: 60
Content-Type: application/json; charset=utf-8
**Impact**
This intermittent 503 behavior causes our service to become unavailable when several concurrent searches overlap with a ClearlyDefined degradation window. The pattern search endpoint is the core of our ClearlyDefined integration.
**Questions**
1. Is there a known backend capacity issue with the pattern search endpoint under concurrent load?
2. Is there a recommended concurrency limit we should respect (even though the rate limit allows 2000/min)?
3. Would batching via [POST /definitions] be more reliable than individual GET /definitions?pattern= calls?
4. Are there any plans to address the intermittent 503s? (Related: #749, #935, #1296)
5. Is there a status page or health endpoint we can poll to detect degradation windows?
Contributor guide
Research direction
Start by reproducing concurrent GET /definitions?pattern=&minDescribedScore=80 requests and recording the documented rate-limit headers, response codes, and latency. Compare the behavior with POST /definitions and review related issues #749, #935, and #1296. Done means identifying the cause or confirmed concurrency limit and documenting a reliable mitigation or backend fix, including how degradation can be detected.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, backend, performance
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100