Kulipa relies on standard HTTP status codes to signify whether an API request was successful or unsuccessful. As a general rule: Status codes in the 2xx series imply success. Status codes in the 4xx series denote an error based on the provided information (for example, a mandatory parameter was not supplied, a charge was unsuccessful, etc.). Status codes in the 5xx series suggest an issue with Kulipa's servers (these are seldom encountered).



Certain 4xx errors that may be programmatically managed (like a declined card) carry an error code that succinctly describes the reported error.

Handling errors

HTTP status code summary

200 OKThe request succeeded.
400 Bad RequestThe server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
401 UnauthorizedAlthough the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
403 ForbiddenThe client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.
404 Not FoundThe server cannot find the requested resource.
429 Too Many RequestsThe user has sent too many requests in a given amount of time ("rate limiting").
500 Internal Server ErrorThe server has encountered a situation it does not know how to handle.
502 Bad GatewayThis error response means that the server, while working as a gateway to get a response needed to handle the request, got an invalid response.
503 Service UnavailableThe server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded.
504 Gateway TimeoutThis error response is given when the server is acting as a gateway and cannot get a response in time.

Error attributes

type(string): The error type describe the type of error returned from Kulipa API. Possible values: ['api_error' , 'rate_limit' , 'invalid_request' , 'request_conflict']
code(string): The business code associated to the error. See errors code list for more details.
message(string): A message that is understandable by humans, offering further information about the error.
details(object): This field provide some extended information regarding the error.

Error body example

  "type": "api_error",
  "code": "card_declined",
  "message": "The card was declined",
  "details": {
    "issuer_reponse_code": 400