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 |
401 Unauthorized |
Missing or invalid API key, or invalid/expired/replayed HelseID token or DPoP proof |
403 Forbidden |
Authenticated via HelseID, but the access token is missing the required nhn:legemiddelgrunndata/api scope |
404 Not found |
Data not found in DB |
429 Too Many Requests |
Rate limit exceeded (see Rate Limiting) |
500 Internal Server Error |
Server error |
Error Format
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.