Repository navigation
Rate Limits and Priority
The API shares its database with ViaFrei's MCP server and website. This page describes how it serves important callers first, refuses fairly and early, never runs past its deadline, and never starves its neighbours.
| # | Gate | Refusal |
|---|---|---|
| 1 | Per-IP flood control before a key is known | 429 rate-limited |
| 2 | Per-key token bucket (rate and burst from the plan) |
429 rate-limited, Retry-After = time until the next token |
| 3 | Daily and monthly quota; the daily reset is at midnight Europe/Berlin, the monthly on the first of the month |
429 quota-exceeded, Retry-After until the reset |
| 4 | Priority admission in front of the database |
429 overloaded (or 503, configurable), with Retry-After
|
Every response carries RateLimit-Policy and RateLimit headers (IETF draft structured fields), so clients can pace themselves before they are refused.
flowchart LR
R[Request past limit and quota] -->|estimated wait fits<br/>the remaining deadline?| A
subgraph A[Admission controller]
Q1[critical queue] --> P((permits =<br/>database pool size))
Q2[standard queue] --> P
Q3[bulk queue<br/>small in-flight cap] --> P
end
P --> DB[(Read contract<br/>hard role connection limit)]
A -.queue full or too slow.-> S[429 overloaded + Retry-After]
- Permits equal the database pool size. Nothing waits inside the connection pool; all waiting happens in the tier queues, where priority applies.
- Weights. A simple feature takes one permit; a composed feature takes one per parallel part.
- Strict priority with reservations. A released permit goes to the highest non-empty tier. Each tier can have reserved permits that lower tiers cannot use, and bulk has its own in-flight cap.
- Aging. A waiter older than a configured age is promoted one tier, so lower tiers cannot starve indefinitely.
- Refuse early. The controller estimates the wait from the queue position and a moving average of service time. If the estimate does not fit the remaining deadline, the request is refused immediately. That costs microseconds and leaves the budget to others.
- Shedding order. Bulk is shed first, then standard; critical only when its own queue is full.
- Optional later: an adaptive concurrency limit (gradient or Vegas style, as popularised by Netflix's concurrency-limits work).
flowchart TD
S[Request arrives: budget = 2 s] --> W[Queue wait spends from the budget]
W --> C{Remaining budget<br/>above the minimum?}
C -->|no| E[503 deadline-exhausted<br/>no query is sent]
C -->|yes| T[Read-only transaction:<br/>statement_timeout = remaining]
T --> Q[Query]
Q -->|done in time| OK[Answer]
Q -->|deadline reached| X[Cancel request sent to PostgreSQL,<br/>connection reused only if clean]
- The budget starts when the request headers are read and is hard-capped at 2 seconds by configuration validation.
- Before each database call, the remaining budget (minus a small reserve) is set as the statement timeout for that transaction, so the database stops the query by itself.
- In addition, when the request is cancelled or its client disconnects, the service sends a PostgreSQL cancel request. A connection is returned to the pool only if it is verifiably idle; otherwise it is discarded.
- Test (design): a stub query that would sleep for five seconds must be answered within the deadline plus a small margin, and the database backend must be idle again shortly after.
- Database-side ceiling: the API's role has a hard connection limit and a role-level statement timeout. Even a defect in the API cannot exceed them.
- Service-side ceiling: admission permits equal the pool size.
- Visibility: in-flight queries and admission wait time are exported as metrics for the operator.
- Assumption: while there is one API instance, no coordination with other services is needed beyond these ceilings. With several instances, shared state is revisited (see Technology: Rate Limiting and Queues).
- Per key, hour and feature: requests, shed requests,
304answers and database time, counted in memory. - Flushed to the access store in one batched write at a configurable interval, and once more on shutdown. There is no database write per request.
- A crash loses at most one flush interval of counts; this is documented.
- The operator reads usage through the command-line tool and, later, the owner console.
- Retention of usage and audit records is configurable (default a little over a year) and pruned automatically.
On a test stack, never production: a small steady stream of critical traffic runs while a bulk flood far above capacity hits a deliberately tiny pool. Pass: critical latency stays within its target; bulk receives 429 with Retry-After; no request runs past 2 seconds. See Benchmark Plan.
| Setting | critical | standard | bulk |
|---|---|---|---|
| Reserved permits | 1 | 0 | 0 |
| Queue length | 32 | 32 | 4 |
| Maximum queue wait | 800 ms | 400 ms | 200 ms |
| In-flight cap | — | — | 1 |
Every value is a configuration key; see Configuration.
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference