Error responses

The data definitions define the structure for the responses, both for successful responses as well as for errors. You can check the responses for a particular definition in the OpenAPI Spec or view it in Swagger UI or ReDoc.

Most definitions have just a specific format for the status code 200 (OK) and use a shared set of default error message structures for the status codes 4xx and 5xx. Most of these error messages share the same structure, which has a type and message field and look for example like this:

This structure applies to the default 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found) and 500 (Internal Server Error) error status codes, which are the most common ones to be used by a data source, as well as most of the errors returned by the data sharing service.

The identifier in the the type field should be in snake_case (lower case letters a-z, numbers 0-9 and underscore are allowed) and easily identify the type of error. For example:

• 401: api_token_missing_or_invalid if the validation of the API token fails, or it is missing.
• 403: forbidden if the API token is valid, but the token does not have permission to request the data specified by the parameters.
• 404: not_found when the requested data can not be found.
• 400 & 500: Informative and identifiable strings for most other errors, such as time_range_validation or upstream_error.

The message field should use a human friendly description.

Reserved and unsupported status codes §

The following status codes are reserved for the use of the IOXIO data sharing service and should not be sent by a data source:

• 444 Data source not found, when the ?source= query parameter defines a data source unknown to the data sharing service, in order to distinguish it from when a data source can’t find data for the given payload and returns a 404 Not Found.
• 502 Bad Gateway, when there’s some problem with the connection to or communication with the data source.
• 503 Service Unavailable
• 504 Gateway Timeout
• 550 Response does not confirm to definition, when the response from the data source either uses a status code that is not defined for the definition, is a reserved status code, or if the data returned by the data source does not match the structure defined in the definition.

Other status codes §

The other status codes present by default in all data definitions are:

• 422 Validation Error is returned by the IOXIO data sharing service when the data in the request does not match the format specified in the definition. The data source should likely not encounter data that is invalid as it’s validated by the data sharing service. Data sources are free to use this, but a generic 400 error with "type": "validation_error" with a human friendly description might be a lot easier to write than generating a response that follows the specified format for this status.
• 429 Too many requests, returned by the IOXIO data sharing service when the rate limit is exceeded. The data source is free to use this as well.

Each data definition can also define custom status codes and responses for them. For details about those, please check the definition case by case.