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 errors

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.

Example:

{
  "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."
}

Troubleshooting:

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.

415 Unsupported Media Type

A 415 error code is returned by a web server to indicate that the server cannot process the request because the client has sent a request with an unsupported or invalid media type or content type in the request headers.

Example:

to be added

Troubleshooting:

Problem	Solution
Incorrect Content Type	Ensure that the "Content-Type" header in the request matches the media type that the server expects. This header specifies the format of the data being sent in the request.
Missing Content Type	Make sure to provide a "Content-Type" header in the request, if the server expects one.
Unsupported Encoding	Check that the data you are sending sending is in a format or encoding that the server understands and supports.

Authorization errors

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.

Example:

{
  "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."
}

Troubleshooting:

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.

Example:

to be added

Troubleshooting:

• Ensure that you have the necessary permissions to access the resource.

429 Too Many Requests

A 429 error code is returned to indicate that the client has sent too many requests in a short period, and the server is rate-limiting or throttling the client's requests to prevent abuse or overloading of the server.

Rate limiting policies are enforced in order to:

• protect the API against severe traffic spikes and denial of service attacks,
• limit the number of API calls apps can make to the API over a specific time window.

Example:

{
    "status": 429,
    "error": "RESOURCE_EXHAUSTED",
    "timestamp": "Tue, 6 Feb 2024 11:16:33 GMT",
    "title": "Rate Limit Exceeded",
    "detail": "You have exceeded the allowed number of requests. Please wait for some time before trying again."
}

Troubleshooting:

• Make sure you are not exceeding the rate limit by sending requests too frequently.

Resource-related errors

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.

Example:

{
  "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.

Example:

{
  "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.

412 Precondition failed

A 412 error code is returned by a web server to indicate that the client's request could not be completed because access to the target resource has been denied. This occurs when one or more user-specified conditions were not fulfilled.

Example:

response to be updated

{
  "errors": [
    {
      "title": "Precondition failed",
      "code": "412",
      "status": 412
    }
  ]
}

Troubleshooting:

• Ensure that the preconditions you set in the request have been fulfilled.

Server-side errors

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.