Errors and limits
Status codes, the error format and rate limiting for the REST data endpoints. Authentication errors (401/403) are described in Authentication; the FHIR endpoints return errors as FHIR OperationOutcome resources, see FHIR R4 endpoints.
HTTP Status Codes
| Code | Meaning |
|---|---|
200 OK |
Success |
400 Bad Request |
Missing or invalid parameter, or conflicting parameters (for example since-version combined with other filters). Returned as application/problem+json |
401 Unauthorized |
Missing or invalid API key (JSON body { "error": "Invalid or missing API key." }), or invalid/expired/replayed HelseID token or DPoP proof (empty body) |
403 Forbidden |
Authenticated via HelseID, but the access token is missing the required nhn:legemiddelgrunndata/api scope (empty body) |
404 Not found |
Data not found in DB. Returned as application/problem+json |
429 Too Many Requests |
Rate limit exceeded (see Rate Limiting). JSON body { "error": "..." } |
500 Internal Server Error |
Server error |
Error Format
400 and 404 responses on the REST data endpoints are application/problem+json (RFC 9457) with type, title, status, traceId and, where relevant, detail:
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "Not Found",
"status": 404,
"traceId": "00-1454e1c1605a87aba254b1fd0890e4df-23713e982938ef77-01"
}
401 (v1, API key) and 429 return a small JSON body, { "error": "<message>" }. The v2 401 and 403 responses have no body.
Unhandled server errors return 500 Internal Server Error with the following JSON body:
{
"correlationId": "3f2b1c9a-4d5e-6f70-8192-a3b4c5d6e7f8"
}
In the Development environment, the body also includes message and stackTrace.
Every response — successful or error — includes an X-Correlation-Id response header. On 500 responses the same value is included in the body as correlationId. Clients may pass their own correlation ID via the X-Correlation-Id request header; it will be reused in the response and in server logs.
If the client aborts the request, no error response is written.
Rate Limiting
The data endpoints (/api/v1/* and /api/v2/*) are rate limited to 120 requests per minute (sliding window). The v1 endpoints are limited per API key; the v2 (HelseID) endpoints are limited per client IP address.
When the limit is exceeded, the API responds with 429 Too Many Requests:
{ "error": "Rate limit exceeded. Try again later." }
The response includes a Retry-After header with the length of the rate-limit window in seconds. Waiting that long guarantees the request budget has fully replenished.
Notes:
- Requests to v1 without a valid API key (missing or unknown) share a single bucket, which also prevents API-key brute-forcing.
- The limit is enforced per server instance (in-memory), so the effective limit across all instances can be higher than 120 requests per minute.
- The Swagger UI is not rate limited.