clearlydefined / clearlydefined/service

GET /definitions?pattern= returns 503 under moderate concurrency despite rate limit not being reached

Open
#1,604 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.