Error handling
Banqup APIs use HTTP response status codes to convey whether a particular HTTP request has been executed successfully or not.
The error responses include details about the failed request to offer additional details regarding the underlying issue.
- Request structure
- Authorization
- Resource-related
- Server-side
400 Bad Request
The HTTP status code 400 Bad Request means that the server was unable to understand the request due to invalid syntax or other issues with the request itself. It indicates that there is something wrong with the way the request was formatted or the data provided in the request.
{
"status": 400,
"error": "BAD_REQUEST",
"timestamp": "Tue, 6 Feb 2024 12:27:24 GMT",
"title": "Invalid Request Format",
"detail": "The request could not be processed due to an invalid format or incorrect data. Please check the request parameters and try again."
}
| Problem | Solution |
|---|---|
| Malformed Request | Check the syntax and structure of the request: missing or incorrect headers, missing parameters, or other issues. |
| Invalid Data | Check that the request doesn't contain invalid data or not in the expected format, such as providing a non-integer value where an integer is expected. |
| Content-Length Mismatch | Check that the the Content-Length header matches the actual size of the content being sent in the request. |
406 Not Acceptable
A 406 error code is returned by a web server to indicate that the server cannot provide a response that matches the requirements of the client (browser) in the request’s Accept headers. The server provides a list of available options that the client can process.
{
"status": 406,
"error": "NOT_ACCEPTABLE",
"requestId": "none",
"timestamp": "2024-10-31T12:34:30.150Z",
"type": "about:blank",
"title": "Not Acceptable",
"detail": "Asset name: 'asset/iam/onboarding/logo', extensions: '[png]', locales: '[]' are not acceptable.",
"instance": "/v1/assets/asset%2Fiam%2Fonboarding%2Flogo"
}
| Problem | Solution |
|---|---|
| Incorrect headers | Check the content type of the header. |
| Unsupported Accept header | Update the Accept header to a different format or remove it and verify if that resolves the issue. |
| Mismatched request and response content types | Update the request to include additional parameters that allow the server to provide a response in the desired format. |
| Requested resource not available in the requested format | Check the server logs and configuration to ensure that it is capable of producing the desired response. |
422 Unprocessable Entity
A 422 error code is returned by a web server to indicate that the server understood the type and syntax of the request content, but it was unable to process the contained instructions due to semantic issues.
{
"status": 422,
"error": "UNPROCESSABLE ENTITY",
"requestId": "a78150d2-7913-4ea6-933f-286cadac6745",
"timestamp": "2018-08-27T12:34:50Z",
"type": "about:blank",
"title": "Unprocessable Entity",
"detail": "Request could not be processed."
}
| Problem | Solution |
|---|---|
| Semantic errors | It means that the data fails to meet the logical rules or business logic defined by the server. Check that the data is logical, complete and compliant to the expected rules. |
| Invalid Data | Check the data type and format in the request. |
| Missing Required Fields | Check that all mandatory fields in the request are filled. |
| Strict Server Rules | Check the data formats and values in the request. |
| Invalid API Requests | Check the parameters and schema used in the API calls. |
401 Unauthorized
A 401 error code is used by a server to indicate that the client's request is missing proper authentication credentials, or the provided credentials are invalid or insufficient to access the requested resource.
401 vs. 403
Note that a 403 error is different from a 401 error, which indicates a lack of authentication, while a 403 error implies that authentication has occurred, but the client lacks the necessary permissions.
{
"status": 401,
"error": "UNAUTHENTICATED",
"timestamp": "Tue, 6 Feb 2024 12:28:34 GMT",
"title": "Authentication Required",
"detail": "Access to this resource is denied due to missing or invalid authentication credentials. Please provide valid credentials and try again."
}
| Problem | Solution |
|---|---|
| Missing or Incorrect Authentication | Ensure that you are providing the correct authentication credentials (e.g., username and password, API token, or OAuth token) in the request. |
| Expired Credentials | Make sure that the provided credentials are valid and have not expired. |
| Insufficient Privileges | Ensure that the authenticated user or client has the necessary permissions to access the requested resource. |
403 Forbidden
A 403 error code is returned by a web server to indicate that the client's request is valid, but the server is refusing to fulfill the request because the client does not have permission to access the requested resource.
401 vs. 403
Note that a 403 error is different from a 401 error, which indicates a lack of authentication, while a 403 error implies that authentication has occurred, but the client lacks the necessary permissions.
{
"status": 403,
"error": "PERMISSION_DENIED",
"requestId": "a78150d2-7913-4ea6-933f-286cadac6745",
"timestamp": "2018-08-27T12:34:50Z",
"type": "about:blank",
"title": "Forbidden",
"detail": "Access to the requested resource was denied."
}
Troubleshooting: Ensure that you have the necessary permissions to access the resource.
404 Not Found
A 404 error code is returned by a web server to indicate that the requested resource, such as a web page or file, could not be found on the server. In other words, the server cannot locate the specific resource that the client is trying to access.
{
"requestId": "a78150d2-7913-4ea6-933f-286cadac6745",
"status": "NOT_FOUND",
"timestamp": "2018-08-27T12:34:50Z",
"message": "The requested resource was not found.",
"debugMessage": "Invalid realm xxx."
}
Troubleshooting: Make sure the requested resource still exists.
409 Conflict
A 409 error code is returned by a web server to indicate that the client's request could not be completed due to a conflict with the current state of the target resource. In other words, the client's request would lead to a conflict with an existing resource, and the server cannot proceed as requested.
{
"status": 409,
"error": "ABORTED",
"requestId": "a78150d2-7913-4ea6-933f-286cadac6745",
"timestamp": "2018-08-27T12:34:50.000Z",
"type": "about:blank",
"title": "Conflict",
"detail": "Specific detail about what could not be done."
}
Troubleshooting: The request conflicts with another request.
5xx error codes
5xx Error codes represent an issue with the server while attempting to fulfill a request. They can be caused by a wide range of issues, including: server misconfiguration, overloaded server, database errors, unhandled exceptions, scheduled maintenance, resource exhaustion, application errors. Generally, they indicate that something has gone wrong on the server, and the specific resolution depends on the root cause of the error.