skip to main content
Official information and services: www.belgium.be belgium.be

Additional guidelines for calling REST APIs

The REST APIs of the Social Security platform are developed in accordance to the Belgif styleguide. In the style guide you can find more details .

Problem handling

Before interpreting the API response payload, the API client should always first evaluate the HTTP status code and decide if the API response was successful (2xx), indicates a client error (4xx) or server error (5xx).

The APIs adopt the Problem Details for HTTP APIs standard (RFC 9457) to communicate errors back to the API client. This standard defines a simple JSON message to convey additional information about the issue complementing the HTTP status codes [RFC7231].

If the Content-Type of the API response is set to application/problem+json, the API client can parse the API response message as a Problem detail.

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
{
   "type": "urn:problem-type:belgif:invalidAccessToken",
   "href": "https://www.belgif.be/specification/rest/api-guide/problems/invalidAccessToken.html",
   "status": 401,
   "title": "Invalid Access Token",
   "detail": "The Bearer access token found in the Authorization HTTP header is invalid"
}
  • The type field always identifies a unique id of the error type in URN format.
  • If present, the href field contains a link to a documentation site explaining the error in more detail.
  • The fields title and detail describe the error in more detail. The messages are written in English and the recipient is the API client developer. The messages should never be shown in an end-user interface.
  • Many problem messages are enriched with additional custom properties, that contain the information from title and description fields in more a structured format. Check the examples per error type for more information.

This is a non-exhaustive list of common error types. Other (API specific) errors are documented in the OpenAPI specification file.

Client

HTTP status code Problem type Description Example
400 Bad Request 
urn:problem-type:belgif:badRequest
 The API request either violates the OpenAPI specification of the API or contains invalid or unexpected input parameters. example
401 Unauthorized 
urn:problem-type:belgif:noAccessToken
 No Bearer access token was found in Authorization HTTP header. example
401 Unauthorized 
urn:problem-type:belgif:invalidAccessToken
 The Bearer access token found in the Authorization HTTP header is invalid. example
401 Unauthorized 
urn:problem-type:belgif:expiredAccessToken
 The Bearer access token found in the Authorization HTTP header has expired. example
403 Forbidden 
urn:problem-type:belgif:missingScope
 The scopes in access token don't provide access to the requested resource (authorization). example
403 Forbidden 
urn:problem-type:belgif:missingPermission
 The access token provides the correct scopes but doesn't provide access to consult or modify the requested resource (data access). example
404 Not Found 
urn:problem-type:belgif:resourceNotFound

The requested resource doesn't exist.

 example
413 Payload Too Large 
urn:problem-type:belgif:payloadTooLarge

The API request is too large and will not be processed.

 example
429 Too many requests 
urn:problem-type:belgif:tooManyRequests

The API client has used all of its quota and should wait to send its next API request.

 example
429 Too many requests 
urn:problem-type:belgif:tooManyFailedRequests

The API client generated too many failures and has been put temporarily on hold.

 example

API

HTTP status code Problem type Description Example
500 Internal Server Error 
urn:problem-type:belgif:internalServerError
 The API encountered an unexpected error and cannot process the API request. example
503 Service Unavailable 
urn:problem-type:belgif:serviceUnavailable
 The API is temporarily inaccessible or in maintenance mode. Please try again later. example

For more information consult the Belgif Styleguide Chapter 13. Error handling

Tracing

In order to uniquely identify requests or response messages, a Trace ID may be added as HTTP header. Trace IDs must be no longer than 36 characters and unique. It's is recommended to use the UUID v4 format.

The Trace ID could be used:

  • for operational purposes, to enable the lookup of related technical logs
  • for audit logging, in order to be able to trace the origin of each request. It may be a legal requirement to have such audit logging when sensitive data is exchanged.

The API will always return its own unique BelGov-Trace-Id in the API response and repeat the optional API request Trace ID in the BelGov-Related-Trace-Id HTTP response header.

Diagram interaction client and API
info
Important
Please store the API response BelGov-Trace-Id HTTP header in your logs and communicate it to the Social Security contact center whenever you open a support request to discuss an API integration issue.

For more information consult the Belgif Styleguide Chapter 16. Tracing

Reference data

Each API normally exposes a list of reference data resources grouped under the common refData path segment. Reference data are code lists, lookup tables etc. specific to the API domain. Since this data is majorly static over time, a recommended practice is to store the reference data in the API client cache and reuse it during 24h or refresh only when a specific reference code couldn't be found.

/refData
/
   /
   /
   /...
/
   /...

For more information please consult the Belgif Styleguide Chapter 10. Refdata

API Versioning

Developers should be attentive to the API evolution and versioning strategy when developing an API client. APIs are versioned using major.minor.bugfix notation but always hosted on a server url that only contains the major version. This means each new minor version replaces its previous minor version. The API designer will guarantee backwards-compatibility with the previous minor version.

openapi: 3.0.3
info:
  title: Demo v1 - REST API
  version: 1.3.2
servers:
  - url: https://services.socialsecurity.be/REST/demo/v1
info
API versions are not by default forward-compatible. The API client developer should program defensively to support API evolution.

Major versions

Major versions of the same APIs are not backwards compatible and require a migration to evolve from a previous to a newer major version.

Minor versions

Minor versions of the same major version are designed to be backwards compatible. The API client developer should be attentive to the following:

  • New resources or operations can be added to an existing API.
  • New fields may be added to response of existing resources. Clients MUST ignore unknown fields in response payloads (lax parsing).
  • New fields can be added to the request of existing resources, but will never be mandatory.
  • Existing fields never change meaning.
  • The request scheme will never be stricter.
  • Enum ranges can be reduced when used as input parameters, only if the server is ready to accept and handle old range values, too.
  • Enum values can be reduced when used as output parameters, but not extended as clients might not be ready to handle them.
  • The client should follow redirections (301 Moved Permanently) in case a URL needs to change.

Bug fix versions

Bug fix versions do not impact the API paths or schemes, they are only corrections in descriptions and examples.

For more information please consult the Belgif Styleguide Chapter 14. Versioning