Skip to content

Spec Errors

mavrovde edited this page Nov 1, 2026 · 1 revision

Spec: Errors

Part of the Technical Specification. Requirement prefix: ERR. Refines the error section of API Design.

1. Problem details

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

2. Catalogue

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).

3. Decision order

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]
Loading

4. Client retry guidance

  • Retry only when retryable is true. Honour Retry-After as a minimum.
  • Otherwise use exponential backoff with full jitter: base 0.5 s, factor 2, cap 30 s, at most 5 attempts.
  • Never retry 4xx other than 429 without changing the request.
  • Composed answers with 200 and a timeout part MAY be repeated after Cache-Control max-age; repeating sooner will usually give the same answer.

Requirements

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

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally