📬 API Response codes and Errors

Response Codes

We use the following HTTP status code in the response depending on the success or failure:

Status CodeDescription
200Success - The content is available in the response body.
201Success - The content was created successfully on Belvo.
204Success - No content to return.
400Bad Request Error - Request returned an error, detail in content.
401Unauthorized - The Belvo credentials provided are not valid.
404Not Found - The resource you try to access cannot be found.
405Method Not Allowed - The HTTP method you are using is not accepted for this resource.
408Request Timeout - The request timed out and was terminated by the server.
428MFA Token Required - MFA token was required by the institution to connect.
500Internal Server Error - The detail of the error is available in the response body.

API Errors

Belvo API errors are returned in JSON format. For example, an error might look like this:

    "request_id": "a6e1c493d7a29d91aed4338e6fcf077d",
    "message": "This field is required.",
    "code": "required",
    "field": "link"

Typically, an error response will have the following parameters:

  • request_id: a unique ID for the request, you should share it with the Belvo support team for investigations.
  • message: human-readable description of the error.
  • code: a unique code for the error. Check the table below to see how to handle each error code.
  • field (optional): The specific field in the request body that has an issue.

Request identifier

When you need help with a specific error, add the request identifier (request_id) in your message to the Belvo support team. This will speed up investigations and get you back up and running in no time at all.

Error codes and troubleshooting

For a full list of errors and how to troubleshoot them, please see our dedicated Error handling articles in our DevPortal.

Retry policy

Please see our recommended retry policies in the DevPortal.