Errors

We use the HTTP status codes to communicate the result of a response. 2xx responses are successful, 4xx responses are failures due to provided information—e.g. a parameter was omitted—and 5xx responses are failures due to banca.me errors.

HTTP Status Code

HTTP Status Code	Description
200	OK - The request was successful
201	Created - The resource was successfully created
400	Bad Request - A parameter has an invalid format, or the token is not your partner's current API token
401	Unauthorized - The Authorization header is missing, or the token is malformed, expired or not signed by banca.me
403	Forbidden - Your partner or partner entity is inactive, or your partner does not have the module the endpoint requires
404	Not Found - The requested resource could not be found
409	Conflict - The request conflicts with the current state of a resource
412	Precondition Failed - A business precondition of the operation is not met
422	Unprocessable Entity - The request was well-formed but its data failed validation
428	Precondition Required - The resource is not in a state that allows the operation
429	Too Many Requests - Rate limit exceeded on a rate-limited endpoint
500	Internal Server Error - Something went wrong on our end
503	Service Unavailable - banca.me or one of its data providers could not complete the request

Each endpoint lists the statuses it returns and what they mean for that endpoint.

Error object

When an error occurs, banca.me will return an error object in the response body. Here's an example of the error structure:

{
  "data": {
    "status": 422,
    "url": "/partner/pre-loan-request",
    "ip": "203.0.113.10",
    "partnerId": "5b0e7c41-2d93-4f8a-a1c6-9e47d2b80f35",
    "message": "ERR_MISSING_BASIC_V2_DATA"
  }
}

Error Object Attributes

Attribute	Type	Description
status	number	The HTTP status code of the response. Left out when the error is unexpected; the response status is then 500.
url	string	Path of the request, including its query string.
ip	string	IP address the request reached banca.me from.
partnerId	string	Partner the token belongs to. Left out when the token could not be read.
message	string	Error code, for example ERR_MISSING_BASIC_V2_DATA. Only included on 422 and 500 responses.
details	object	Additional information, for the errors that provide it.
appUrl	string	Value of the request's Origin header, when the request sent one.
tokenIntention, preLoanRequestId, preApproveId, widgetMode, productType, partnerEntityId	string	Taken from the token when it carries them. API tokens don't carry them.

Error codes

Only 422 and 500 responses include the error code in message. Responses with any other status don't include it, so handle those by their HTTP status.

Rate limits

Some endpoints limit how many requests you can make in a short time window. When the limit is exceeded they answer 429 with a plain-text body (You have reached maximum retries in this timespan.) instead of the error object, and with the Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.