Repository navigation
Spec Errors
Part of the Technical Specification. Requirement prefix: ERR. Refines the error section of API Design.
Every error is an RFC 9457 problem details object with media type application/problem+json:
{
"type": "https://api.viafrei.de/problems/invalid-parameter",
"title": "Invalid parameter",
"status": 400,
"detail": "radius_m must be between 1 and 50000.",
"instance": "/v1/charging-options",
"requestId": "0192e3b4-7c1a-7d2e-9a10-5b6c7d8e9f01",
"retryable": false,
"errors": [
{"parameter": "radius_m", "code": "out_of_range", "detail": "must be between 1 and 50000", "pointer": null}
]
}| Member | Rule |
|---|---|
type |
Absolute URI https://api.viafrei.de/problems/<slug>; stable forever; resolves to a documentation page |
title |
Short, fixed per type, in the response language |
status |
Equal to the HTTP status |
detail |
Human-readable, specific to this occurrence; never contains internal names, stack traces, SQL, hostnames or secrets |
instance |
The request path without the query string |
requestId |
Equal to X-Request-Id (extension member) |
retryable |
Whether repeating the same request may succeed (extension member) |
retryAfter |
Seconds, equal to Retry-After, where applicable (extension member) |
errors[] |
For invalid-parameter: one entry per violation with parameter (query or path name) or pointer (RFC 6901, for a query POST body), code, detail
|
candidates[] |
For ambiguous-place: the candidate places |
| Status | Type slug | When | Retryable |
|---|---|---|---|
| 400 | invalid-parameter |
A parameter is missing, malformed, out of range, unknown or repeated | no |
| 400 | invalid-cursor |
A cursor is tampered, expired, foreign or used with other filters | no |
| 400 | window-required |
A history request without from and to
|
no |
| 400 | window-too-large |
A time window above its configured maximum | no |
| 400 | key-in-query |
A key appears in the query string; the key is also treated as exposed | no |
| 401 | missing-key |
No key presented | no |
| 401 | invalid-key |
Unknown key, wrong checksum or wrong secret (one answer for all three) | no |
| 401 | key-expired |
The key's expiry has passed | no |
| 401 | key-revoked |
The key was revoked | no |
| 403 | scope-denied |
The key's plan lacks the operation's scope, or a history window reaches beyond the plan's depth | no |
| 403 | source-not-permitted |
Every family that could answer is outside the key's licence permissions | no |
| 403 | terms-not-accepted |
The only answering family requires terms the key has not accepted | no |
| 404 | not-found |
Unknown path, unknown id, unknown road, or a text that matches no place | no |
| 404 | feature-disabled |
The operation is switched off by configuration | no |
| 405 | method-not-allowed |
Method not supported on this path | no |
| 406 | not-acceptable |
No offered media type is acceptable | no |
| 412 | precondition-failed |
If-Match or If-Unmodified-Since fails |
no |
| 413 | payload-too-large |
Query body above server.max_body_bytes
|
no |
| 414 | uri-too-long |
URI above server.max_uri_bytes
|
no |
| 415 | unsupported-media-type |
Query body not application/json
|
no |
| 422 | ambiguous-place |
A place text matches several places | no (refine the input) |
| 422 | outside-coverage |
A location outside the coverage area | no |
| 422 | area-too-large |
A radius, box, route or corridor above its limit | no |
| 422 | invalid-section |
Section ends that do not lie on the named road | no |
| 429 | rate-limited |
Per-IP or per-key rate exceeded | yes, after Retry-After
|
| 429 | quota-exceeded |
Daily or monthly quota used up | yes, after the reset in Retry-After
|
| 429 | overloaded |
Priority admission refused: the estimated wait does not fit the deadline | yes, after Retry-After
|
| 431 | headers-too-large |
Request header fields above server.max_header_bytes
|
no |
| 500 | internal |
An unexpected fault, including a licence post-check violation | yes, once, with backoff |
| 503 | deadline-exhausted |
The 2 second deadline expired in the queue or during the read | yes, after Retry-After
|
| 503 | upstream-unavailable |
Storage is unavailable or its circuit is open | yes, after Retry-After
|
| 503 | not-ready |
The instance is starting or draining | yes |
| 504 | (edge) | Produced only by the TLS edge if the service gives no answer at all; the service itself never emits 504 because its own deadline yields 503 deadline-exhausted first |
yes, with backoff |
409 is not used. The API is read-only and has no resource state that a request can conflict with. An ambiguous place, listed as 409 in earlier drafts, is 422 ambiguous-place: the request is well formed but its meaning cannot be resolved (RFC 9110 section 15.5.21).
overloaded uses 429 by default; the operator MAY switch it to 503 with admission.shed_status (Rate Limits and Priority).
flowchart TD
A[Request] --> L{Size and syntax limits}
L -->|exceeded| E1[413, 414, 431]
L --> M{Method and path}
M -->|unknown path| E2[404 not-found]
M -->|bad method| E3[405]
M --> N{Acceptable media type}
N -->|no| E4[406]
N --> I{Per-IP flood}
I -->|over| E5[429 rate-limited]
I --> K{Key}
K -->|bad| E6[400 key-in-query or 401]
K --> S{Scope and licence gate}
S -->|denied| E7[403]
S --> V{Parameters}
V -->|bad| E8[400 or 422]
V --> Q{Rate and quota}
Q -->|over| E9[429]
Q --> C{Preconditions}
C -->|fail| E10[412 or 304]
C --> D{Admission and deadline}
D -->|refused| E11[429 overloaded or 503]
D --> OK[200]
- Retry only when
retryableis true. HonourRetry-Afteras a minimum. - Otherwise use exponential backoff with full jitter: base 0.5 s, factor 2, cap 30 s, at most 5 attempts.
- Never retry
4xxother than429without changing the request. - Composed answers with
200and atimeoutpart MAY be repeated afterCache-Controlmax-age; repeating sooner will usually give the same answer.
| ID | Requirement | Verification |
|---|---|---|
| ERR-001 | Every 4xx and 5xx answer produced by the service MUST be application/problem+json with type, title, status, detail, instance, requestId and retryable. |
Contract |
| ERR-002 | Problem type URIs MUST be stable for the life of the major version and MUST each resolve to a documentation page. | Docs |
| ERR-003 | The set of types MUST be closed per major version for each status: a new type MAY be added only as a refinement, and clients MUST handle an unknown type by its status. |
Contract |
| ERR-004 |
detail and every other member MUST NOT contain stack traces, query text, storage names, hostnames, addresses, key material or the existence of another key's resources. |
Security |
| ERR-005 |
invalid-parameter MUST list every violation found, not only the first. |
Handler |
| ERR-006 | All 401 answers MUST carry WWW-Authenticate: Bearer realm="viafrei-api" with error="invalid_token" (or no error for missing-key), and invalid-key MUST NOT reveal whether the key id exists. |
Security |
| ERR-007 | Every 429 and every 503 MUST carry Retry-After in seconds and the same value in retryAfter. |
Handler |
| ERR-008 | An unexpected fault MUST yield 500 internal with the request id; the details go only to the log. |
Handler |
| ERR-009 |
409 MUST NOT be emitted. |
Contract |
| ERR-010 | A composed answer MUST NOT turn a part failure into an error status while any part is ok (FR-BRIEF-005). |
Handler |
| ERR-011 |
title MUST be localised to the response language; type and errors[].code MUST NOT be. |
Handler |
| ERR-012 | Error responses MUST carry the rate-limit headers when a key was identified, so that a client can pace itself after a refusal. | Handler |
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