diff --git a/docs/specs/modules/booking.definitions.yaml b/docs/specs/modules/booking.definitions.yaml
index d2599a74..0cb692b6 100644
--- a/docs/specs/modules/booking.definitions.yaml
+++ b/docs/specs/modules/booking.definitions.yaml
@@ -6,14 +6,14 @@ BookingsCountResponse:
 BookingsResponse:
   properties:
     bookings:
-      $ref: '/specs/modules/booking.definitions.yaml#/ConfirmedBookingData'
+      $ref: '#/ConfirmedBookingData'
     count:
       type: number
 
 ConfirmedBookingData:
   properties:
     confirmation:
-      $ref: '/specs/modules/booking.definitions.yaml#/LocalizedBookingConfirmationInfo'
+      $ref: '#/LocalizedBookingConfirmationInfo'
     trips:
       type: array
       items:
@@ -28,17 +28,17 @@ ConfirmedBookingData:
 LocalizedBookingConfirmationInfo:
   properties:
     provider:
-      $ref: '/specs/modules/booking.definitions.yaml#/Detail'
+      $ref: '#/Detail'
     vehicle:
-      $ref: '/specs/modules/booking.definitions.yaml#/Detail'
+      $ref: '#/Detail'
     status:
-      $ref: '/specs/modules/booking.definitions.yaml#/Detail'
+      $ref: '#/Detail'
     purchase:
-      $ref: '/specs/modules/booking.definitions.yaml#/Purchase'
+      $ref: '#/Purchase'
     actions:
       type: array
       items:
-        $ref: '/specs/modules/booking.definitions.yaml#/Action'
+        $ref: '#/Action'
 
 Detail:
   properties:
@@ -75,9 +75,9 @@ Purchase:
     valid:
       type: boolean
     brand:
-      $ref: '/specs/tripgo.swagger.yaml#/definitions/CompanyInfo'
+      $ref: '../tripgo.swagger.yaml#/definitions/CompanyInfo'
     source:
-      $ref: '/specs/tripgo.swagger.yaml#/definitions/DataSourceAttribution'
+      $ref: '../tripgo.swagger.yaml#/definitions/DataSourceAttribution'
 
 Action:
   properties:
@@ -106,7 +106,7 @@ Action:
       description: "if present, the internalURL requires a POST with a JSON object with a field named 'input' and a list of objects with the exact format of these ones, but having the value field completed as expected"
       type: array
       items:
-        $ref: '/specs/modules/booking.definitions.yaml#/ActionInput'
+        $ref: '#/ActionInput'
 
 ActionInput:
   properties:
@@ -140,7 +140,7 @@ AuthData:
     modeIdentifier:
       type: string
     companyInfo:
-      $ref: '/specs/tripgo.swagger.yaml#/definitions/CompanyInfo'
+      $ref: '../tripgo.swagger.yaml#/definitions/CompanyInfo'
 
 BookingAction:
   type: object
@@ -167,14 +167,14 @@ BookingAction:
 BookingForm:
   properties:
     action:
-      $ref: '/specs/modules/booking.definitions.yaml#/BookingAction'
+      $ref: '#/BookingAction'
     prevAction:
-      $ref: '/specs/modules/booking.definitions.yaml#/BookingAction'
+      $ref: '#/BookingAction'
     form:
       description: The list of FormGroups to show in the form.
       type: array
       items:
-        $ref: '/specs/modules/booking.definitions.yaml#/FormGroup'
+        $ref: '#/FormGroup'
     image:
       description: 'a URL of an image to show, whenever available'
       type: string
@@ -200,25 +200,25 @@ BookingForm:
 
 PaymentForm:
   allOf:
-    - $ref: '/specs/modules/booking.definitions.yaml#/BookingForm'
+    - $ref: '#/BookingForm'
     - type: object
   description: Generic data to generate input fields on a payment booking screen
 
 AuthForm:
   allOf:
-    - $ref: '/specs/modules/booking.definitions.yaml#/BookingForm'
+    - $ref: '#/BookingForm'
     - type: object
   description: Generic data to generate input fields on an auth booking screen
 
 BookingFormField:
   allOf:
-    - $ref: '/specs/modules/booking.definitions.yaml#/FormField'
+    - $ref: '#/FormField'
     - type: object
     - properties:
         action:
-          $ref: '/specs/modules/booking.definitions.yaml#/BookingAction'
+          $ref: '#/BookingAction'
         prevAction:
-          $ref: '/specs/modules/booking.definitions.yaml#/BookingAction'
+          $ref: '#/BookingAction'
         form:
           description: The list of FormGroups to show in the form, not described properly on purpose to avoid infinite loop
           type: array
@@ -248,7 +248,7 @@ BookingFormData:
       description: ''
       type: array
       items:
-        $ref: '/specs/modules/booking.definitions.yaml#/FormField'
+        $ref: '#/FormField'
   description: ''
 
 FormField:
@@ -304,7 +304,7 @@ FormField:
 
 StringFormField:
   allOf:
-    - $ref: '/specs/modules/booking.definitions.yaml#/FormField'
+    - $ref: '#/FormField'
     - type: object
     - properties:
         value:
@@ -324,16 +324,16 @@ StringFormField:
 
 AddressFormField:
   allOf:
-    - $ref: '/specs/modules/booking.definitions.yaml#/FormField'
+    - $ref: '#/FormField'
     - type: object
     - properties:
         value:
           description: 'value of the field, to be shown and filled/updated by the user, and sent to the backend if required'
-          $ref: '/specs/modules/booking.definitions.yaml#/Location'
+          $ref: '../tripgo.swagger.yaml#/definitions/Location'
 
 DateTimeFormField:
   allOf:
-    - $ref: '/specs/modules/booking.definitions.yaml#/FormField'
+    - $ref: '#/FormField'
     - type: object
     - properties:
         value:
@@ -344,7 +344,7 @@ DateTimeFormField:
 
 StepperFormField:
   allOf:
-    - $ref: '/specs/modules/booking.definitions.yaml#/FormField'
+    - $ref: '#/FormField'
     - type: object
     - properties:
         value:
@@ -359,7 +359,7 @@ StepperFormField:
 
 TimeFormField:
   allOf:
-    - $ref: '/specs/modules/booking.definitions.yaml#/FormField'
+    - $ref: '#/FormField'
     - type: object
     - properties:
         value:
@@ -368,7 +368,7 @@ TimeFormField:
 
 PasswordFormField:
   allOf:
-    - $ref: '/specs/modules/booking.definitions.yaml#/FormField'
+    - $ref: '#/FormField'
     - type: object
     - properties:
         value:
@@ -377,7 +377,7 @@ PasswordFormField:
 
 LinkFormField:
   allOf:
-    - $ref: '/specs/modules/booking.definitions.yaml#/FormField'
+    - $ref: '#/FormField'
     - type: object
     - properties:
         value:
@@ -393,7 +393,7 @@ LinkFormField:
 
 TextFormField:
   allOf:
-    - $ref: '/specs/modules/booking.definitions.yaml#/FormField'
+    - $ref: '#/FormField'
     - type: object
     - properties:
         value:
@@ -402,7 +402,7 @@ TextFormField:
 
 SwitchFormField:
   allOf:
-    - $ref: '/specs/modules/booking.definitions.yaml#/FormField'
+    - $ref: '#/FormField'
     - type: object
     - properties:
         value:
@@ -411,16 +411,16 @@ SwitchFormField:
 
 OptionFormField:
   allOf:
-    - $ref: '/specs/modules/booking.definitions.yaml#/FormField'
+    - $ref: '#/FormField'
     - type: object
     - properties:
         value:
           description: 'value of the field, to be shown and filled/updated by the user, and sent to the backend if required'
-          $ref: '/specs/modules/booking.definitions.yaml#/OptionData'
+          $ref: '#/OptionData'
         allValues:
           description: 'list of available values to show to the user'
           items:
-            $ref: '/specs/modules/booking.definitions.yaml#/OptionData'
+            $ref: '#/OptionData'
 
 OptionData:
   properties:
@@ -439,7 +439,7 @@ OptionData:
 
 ExternalFormField:
   allOf:
-    - $ref: '/specs/modules/booking.definitions.yaml#/FormField'
+    - $ref: '#/FormField'
     - type: object
     - properties:
         value:
@@ -461,7 +461,7 @@ FormGroup:
       description: ''
       type: array
       items:
-        $ref: '/specs/modules/booking.definitions.yaml#/FormField'
+        $ref: '#/FormField'
     footer:
       description: ''
       type: string
diff --git a/docs/specs/tripgo.openapi.yaml b/docs/specs/tripgo.openapi.yaml
index 6236d797..38c50967 100644
--- a/docs/specs/tripgo.openapi.yaml
+++ b/docs/specs/tripgo.openapi.yaml
@@ -1086,69 +1086,103 @@ paths:
           type: boolean
           default: true
       responses:
+        "400":
+          description: Bad request.
+          headers:
+            X-TripGo-ErrorCode:
+              schema:
+                type: integer
+              description: the error code in the response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RoutingFailure'
+        "500":
+          description: Server error.
+          headers:
+            X-TripGo-ErrorCode:
+              schema:
+                type: integer
+              description: the error code in the response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RoutingFailure'
+        "503":
+          description: Service Unavailable
+          headers:
+            X-TripGo-ErrorCode:
+              schema:
+                type: integer
+              description: the error code in the response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RoutingFailure'
         "200":
           description: Successful response. Can include many trips.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/RoutingResponse'
-            Location missing:
-              example:
-                error: From and/or to location missing.
-                errorCode: 400
-                usererror: true
-            Server doesn't have from region:
-              example:
-                error: Server doesn't have 'from' region | Server doesn't have 'to'
-                  region
-                errorCode: 401
-                usererror: true
-            Server doesn't have to region:
-              example:
-                error: Server doesn't have 'from' region | Server doesn't have 'to'
-                  region
-                errorCode: 401
-                usererror: true
-            Routing between locations not sopported:
-              example:
-                error: Routing between these locations is not yet supported.
-                errorCode: 1001
-                usererror: true
-            Origin outside area:
-              example:
-                error: Origin lies outside covered area.
-                errorCode: 1002
-                usererror: true
-            Destination outside area:
-              example:
-                error: 1003
-                errorCode: Destination lies outside covered area.
-                usererror: true
-            Destination equals origin:
-              example:
-                error: 1101
-                errorCode: Destination equals origin.
-                usererror: true
-            No from set:
-              example:
-                error: 1102
-                errorCode: No 'from' location set. Please try again.
-                usererror: true
-            No to set:
-              example:
-                error: 1103
-                errorCode: No 'to' location set. Please try again.
-                usererror: true
-            Departure in the past:
-              example:
-                error: 1202
-                errorCode: Departure time is too far in the past for public transport.
-                usererror: true
-            Arrival in the past:
-              example:
-                error: 1203
-                errorCode: Arrival time is too far in the past for public transport.
-                usererror: true
+              examples:
+                Location missing:
+                  value:
+                    error: From and/or to location missing.
+                    errorCode: 400
+                    usererror: true
+                Server doesn't have from region:
+                  value:
+                    error: Server doesn't have 'from' region | Server doesn't have 'to'
+                      region
+                    errorCode: 401
+                    usererror: true
+                Server doesn't have to region:
+                  value:
+                    error: Server doesn't have 'from' region | Server doesn't have 'to'
+                      region
+                    errorCode: 401
+                    usererror: true
+                Routing between locations not sopported:
+                  value:
+                    error: Routing between these locations is not yet supported.
+                    errorCode: 1001
+                    usererror: true
+                Origin outside area:
+                  value:
+                    error: Origin lies outside covered area.
+                    errorCode: 1002
+                    usererror: true
+                Destination outside area:
+                  value:
+                    error: 1003
+                    errorCode: Destination lies outside covered area.
+                    usererror: true
+                Destination equals origin:
+                  value:
+                    error: 1101
+                    errorCode: Destination equals origin.
+                    usererror: true
+                No from set:
+                  value:
+                    error: 1102
+                    errorCode: No 'from' location set. Please try again.
+                    usererror: true
+                No to set:
+                  value:
+                    error: 1103
+                    errorCode: No 'to' location set. Please try again.
+                    usererror: true
+                Departure in the past:
+                  value:
+                    error: 1202
+                    errorCode: Departure time is too far in the past for public transport.
+                    usererror: true
+                Arrival in the past:
+                  value:
+                    error: 1203
+                    errorCode: Arrival time is too far in the past for public transport.
+                    usererror: true
 
   /waypoint.json:
     post:
@@ -1242,7 +1276,7 @@ paths:
                     \ day."
                   items:
                     $ref: '#/components/schemas/PrivateVehicle'
-            examples:
+            example:
               - summary: "Home to work to lunch to work to home"
                 value:
                   config:
@@ -2649,13 +2683,37 @@ components:
       properties:
         error:
           type: string
+          description: "A description of the error"
         errorCode:
           type: integer
+          description: | 
+            Code of the error. <br> 
+            <table>
+              <thead>
+                <tr><th>Code</th><th>Description</th></tr>
+              </thead>
+              <tbody>
+                <tr><td>1101</td><td>destination is too close to the origin</td></tr>
+                <tr><td>1102</td><td>no origin has been supplied</td></tr>
+                <tr><td>1103</td><td>no destination has been supplied</td></tr>
+                <tr><td>1001</td><td>location combination is not supported</td></tr>
+                <tr><td>1002</td><td>origin is not supported</td></tr>
+                <tr><td>1003</td><td>destination is not supported</td></tr>
+                <tr><td>1202</td><td>departure time is too old</td></tr>
+                <tr><td>1203</td><td>arrival time is too old</td></tr>
+                <tr><td>1401</td><td>servers does not have at least one of the following: origin region or destination region</td></tr>
+                <tr><td>1402</td><td>blacklist and whitelist are mutually exclusive</td></tr>
+                <tr><td>1403</td><td>invalid query. micro mobility type missing: a particular micro mobility type, e.g. <code>me_mic_bic</code> is needed</td></tr>
+                <tr><td>1404</td><td>invalid query: wrong taxi identifier for expected taxi waiting time</td></tr>
+                <tr><td>0</td><td>unknown</td>
+                </tr>
+              </tbody>
+            </table>
         usererror:
-          type: boolean          
+          type: boolean
+          description: "if this error should be shown to the user"
       required:
         - error
-        - errorCode
         - usererror
 
     ConfigInput:
@@ -2993,7 +3051,7 @@ components:
           description: ID of the product in externalActions (currently only used for
             Uber and Lyft)
         confirmation:
-          $ref: /specs/modules/booking.definitions.yaml#/LocalizedBookingConfirmationInfo
+          $ref: "./modules/booking.definitions.yaml#/LocalizedBookingConfirmationInfo"
     Color:
       required:
       - blue