HTTP status codes
DRACOON's REST API makes use of several standardized HTTP status codes to signal whether a certain request could be fulfilled successfully. When implementing a client, you might receive the following status codes:
| 200 | The request could be fulfilled successfully. Should be the standard response code of GET APIs. |
| 201 | The request could be fulfilled successfully, and a resource has been created. |
| 202 | We successfully received all your information, and everything is alright so far. However, the request is still being processed, and it might take the server a while to complete it. |
| 204 | The request could be fulfilled successfully. However, you will not receive any further data in the response body. |
| 302 | Redirect. Please retrieve the requested resource from the provided URL. |
| 400 | Bad Request. The client provided data in its request that is either not parsable or contains illegal values so that the request is invalid. Please see error code and debug message for further information. |
| 401 | Authentication required. During authentication, this status code is returned on invalid login credentials; in all other situations, it means that the authentication token you provided is not valid (anymore). |
| 403 | Authorization required. This status code is returned whenever a request is sent that requires more rights or permissions than the currently authenticated user has. |
| 404 | Not found. The client requested a resource that cannot be found. |
| 409 | The request cannot be fulfilled because it is prevented by a conflict. Please see error code and debug message for further information. |
| 412 | There are some cases in which this status code is returned. Usually, the user has to execute some action before proceeding (e.g. change his/her password). Please see error code and debug message for further information. |
| 429 | Too many requests. This means your application made too many requests in a given timeframe. If you receive this error, you should throttle your requests. |
| 500 | Internal Server Error. You should never encounter this status code. If you do, you found a bug in our software, and we politely ask you to inform us about this issue in detail so we can fix this issue. Thank you! |
| 502 | This is a status provided by a reverse proxy if the infrastructure is not working correctly. Please inform the administrator about this issue. |
| 503 | You will receive this status code during the downtime of our application. Please stay tuned, and we will probably fix this issue in a very short time. |
| 504 | If you receive this status code from a reverse proxy, a timeout occurred. This should be fixed in a very short time by our infrastructure team. |
Error codes
General
In addition to HTTP status codes, DRACOON API often provides individual error codes to inform the client developer or the user in more detail about the current issue. Each error code is accompanied by an individual debug message to provide human-readable information about the problem that occurred.
We collect all possible error codes and error messages in the Swagger Documentation.
Security considerations
Specific details about certain errors might be abused by an attacker to gain knowledge or to receive leaked information about the system and its users. An example of this could be the specific details of an unsuccessful login: If the system informs the requester that a user with the provided user name was found, but the password was not correct, an external attacker can gain insights about existing user accounts which violates their privacy. To avoid this, DRACOON API only informs that the combination of user name and provided password is not valid to log on.
Whenever we implement a specific error code and error message, we ask ourselves whether this could disclose sensitive information to an attacker. In these cases, the security and privacy of our users and the system as a whole are the higher value than a helpful and detailed notification of client developers or end-users. This is why you might encounter several error situations in which we do not provide you with a specific error code and a specific error message about what actually went wrong.
Comments
0 comments
Article is closed for comments.