Error Reference

Common Error Reference

DTN Weather APIs use the standard HTTP status codes as error codes. The HTTP response status codes are a widely-used standard for all HTTP requests. Using them as a standard reference gives us the benefit of common context engineers are already familiar with, eliminating the need for an additional layer of interpretation.

For reference, this page contains common status codes and how they are used in the context of DTN Weather APIs.

HTTP Response Classes

HTTP response codes can be grouped into classes: Information responses (1xx), Successful responses (2xx), Redirect responses (3xx), Client errors (4xx), Server errors (5xx)

For DTN Weather APIs, the most important and more commonly used are the 2xx, 4xx, and 5xx responses.

Success responses (2xx)

This class of status code indicates that the client's request was successfully received, understood, and accepted.

Client errors (4xx)

This group of HTTP status codes includes those where the request contains bad syntax or cannot be filled for some other reason, presumably by the fault of the client.

Server errors (5xx)

This group of HTTP status codes includes those where the request is understood by the server but is incapable of filling it for some reason - most likely by the fault of the server.

Common Status Codes Used in DTN Weather APIs

Status	Description	Formal Description	Possible Cause	User Impact
200	OK	The request has succeeded. The information returned with the response is dependent on the method used in the request.	Operation has succeeded.	User receives all requested data.
400	Bad Request	The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.	Request created by user contains parameters which are not available in the system and are not recognized by server. Example - user is requesting for weather parameter which is not provided by Point Forecast Service.	User does not receive any data. He needs to modify his request first.
401	Unauthorized	The request requires user authentication. The response MUST include a WWW-Authenticate header field (in Weather API - Authorization Bearer Token). If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials - token is no longer valid.	Two possibilities: User has not attached authentication token to the request (bearer token) User has attached authentication token which has already expired (token used in Weather API services is valid for one hour) In Weather API service for token generation and renewal is responsible auth-server. If auth-server is down then renewing or token generation is impossible.	User does not receive any data. A valid authentication token must be obtained before making a new request.
403	Forbidden	The client does not have access rights to the content, but its identity is known to the server.	User has crated proper request (all parameters are known to the server, attached token is valid) but he is trying to get data which is not allowed for him. It might be part of data in one service, but also whole service (access to POSI, but not for MOSI) Example - scopes in the Radar Precipitation Forecast. User has access only to radar data in Germany. If he will request for radar data from France he will in return get 403 status code.	User does not receive any data. User must send a request to a service the user is permitted OR request customer service to extend scope of the client ID.
404	Not Found	The server can not find requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist.	User has created a request which is trying to get to a part of the system which does not exist. Example - in Station Metadata Service user is trying to get data from endpoint "/meteogroupStations". There is no such endpoint (should use "/stations") so in return he will get 404 status code.	User will not receive any data. User needs to update the request. Refer to the Weather API documentation for available endpoints.
500	Internal Server Error	The server has encountered a situation it doesn't know how to handle.	After user request an unexpected situation occurred and server could not resolve the request. In this case there is an issue on the server side - it might be that some of the implementation was not prepared for all cases and exceptional situation was not handled properly.	User will not receive any data. User can check the request if it is proper and the API is used properly. If issue persists, contact support.
502	Bad Gateway	This error response is given when the server is acting as a gateway and cannot get a proper response from the underlying service	Service is not receiving any request - Load Balancer or API Gateway is not able to pass the request from user to any instance of the service. It is strictly connected to the server issue. It might be that server is down - 0 online instances or there where two many requests at same moment and service became unavailable/is restarting.	User will not receive any data. User can wait a few minutes and retry the request. If it takes too long and issue persists, contact support.
503	Service Unavailable	The server is not ready to handle the request. Common causes are a server is down or that is overloaded.	Service is not receiving any request - Load Balancer or API Gateway is not able to pass the request from user to any instance of the service. It is strictly connected to the server issue. It might be that server is down - 0 online instances or there where two many requests at same moment and service became unavailable/is restarting.	User will not receive any data. User can wait a few minutes and retry the request. If it takes too long and issue persists, contact support.
504	Gateway Timeout	This error response is given when the server is acting as a gateway and cannot get a response in time.	The server is taking too long to process the request data. Each service has is own timeout period. If in that period service will not finish processing the request, the end user will receive 504 status code for Load Balancer or Api Gateway (depends on service). For example it might be related to rapid number of request growth and at the same time too many connections to the database so the service needs to wait for data.	User will not receive any data. User can wait a few minutes and retry the request. If it takes too long and issue persists, contact support.