Timeouts and error handling

Make API calls failsafe

Since the API is often called at critical points in an application (i.e. user registration, during a transaction), it's important to write failsafe code.

It's usually best to log errors but not block your application flow. If you're using Hitprobe to screen new user registrations, it's often preferable to allow the sign up to proceed even if the API call to Hitprobe fails. This is what is meant by failsafe. So consider structuring your code so that errors are flagged up to you but there is no effect on the user.

HTTP errors

You'll likely already be familiar with HTTP errors, all you need to do is make sure that you handle connection errors, set a reasonable HTTP timeout, and check you receive a 200 status code.

Here is an example of setting the timeout at 15 seconds:

cURL

curl 'https://app.hitprobe.com/api/v1/event' \
    -H 'Content-Type: application/json' \
    --data '...' \
    --max-time 15

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->post('https://app.hitprobe.com/api/v1/event', [
    'headers' => [
        'Content-Type' => 'application/json'
    ],
    'body' => '...',
    'timeout' => 15
]);

Python

import requests

headers = {
    'Content-Type': 'application/json',
}

data = '...'
response = requests.post('https://app.hitprobe.com/api/v1/event', headers=headers, data=data, timeout=15)

Go

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"strings"
	"time"
)

func main() {
	client := &http.Client{
		Timeout: 15 * time.Second,
	}
	var data = strings.NewReader(`...`)
	req, err := http.NewRequest("POST", "https://app.hitprobe.com/api/v1/event", data)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Content-Type", "application/json")
	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	bodyText, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s\n", bodyText)
}

Java

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse;
import java.time.Duration;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://app.hitprobe.com/api/v1/event"))
    .POST(BodyPublishers.ofString("..."))
    .setHeader("Content-Type", "application/json")
    .timeout(Duration.ofSeconds(15))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Lookup errors

Hitprobe's architecture is highly distributed, and so each API request triggers many sub-operations that often depend on third-party responses or microservices within Hitprobe's own network.

Very occasionally, an individual check will fail. When this happens, its success property will be set to false. Failures are rare, but bear in mind that an individual lookup will not fail the whole response (you will still receive a 200 status code and potentially data on successful lookups).

For example, if the phone check fails, you will receive:

{
    ...
    "phone": {
        "success": false
    }
    ...
}

Using lookup data

After you successfully receive a result, and if you need to make use of lookup data, you should check its success first. I.e. To use the phone lookup details, first check that phone.success is true.

Note that the top-level properties themselves (email, phone, etc.) are guaranteed to exist in the response, as well as the success and valid sub-properties, but other fields may be missing where the lookup is not successful or where the provided value is not valid. That's why it's a good idea to check that both success and valid is true before reading the data, or alternatively write code that expects missing properties.