Skip to main content

Error handling

As an integrator, there are certain rules and processes you need to follow regarding error handling. If you send too many bad requests, you might be suspended from using the Kisi API until the issues have been fixed.

HTTP statuses​

When making requests to the Kisi API, you need to check the HTTP status code that is returned and act accordingly. Kisi follows the standard HTTP statuses, which can be grouped into the following categories:

  • 2xx: Any 2xx status is regarded as a successful request.
  • 3xx: Different kinds of redirects.
  • 4xx: Client errors. Common examples are 401 which indicates a failure to authenticate, like a bad password, or 403 where the authenticated user is not allowed to perform the specific request, or 422 which means the request could not be processed (often due to an invalid payload, such as a missing or invalid attribute).
  • 5xx: Server errors. This could be due to a bug in the Kisi system.

Retries​

If you receive a 4xx response, it means something is wrong with the request or the user simply does not have access to perform the request. In general, it doesn't help to automatically retry these requests. Instead, you need to investigate what is wrong with the request and correct it before retrying. One exception is the 429 status, which indicates a rate limit. Read more about rate limits below.

If you receive a 5xx response, a retry might work. However, it's important to have an appropriate retry strategy such as exponential backoff.

Rate limiting​

The Kisi API applies rate limiting, which varies between endpoints. When a client is rate-limited, the API returns status code 429. It's important that you handle these errors in a reasonable manner and apply a good retry strategy, such as exponential backoff. More information about rate limiting can be found in the API reference.

Error tracking​

It's also important that you track the statuses and make sure you are not sending too many failed requests to the API. If you have a lot of failed requests, you need to investigate and fix them. If you suspect there is an issue with the Kisi API, please report them to Kisi Support.