Skip to main content

Efficient API usage

Our API is fast, but that's only one part of the equation. A bad client setup can easily add hundreds of milliseconds per request; a good one makes the API feel instant.

This page covers everything you need to squeeze the most out of api.verislabs.io.

HTTP versions: HTTP/1.1 vs HTTP/2 vs HTTP/3​

HTTP/1.1 and HTTP/2 are supported on https://api.verislabs.io:

  • HTTP/2 - available by default in most clients. This is what you should use.
  • HTTP/1.1 - works fine, but lacks multiplexing and header compression.
  • HTTP/3 (QUIC) - we do not support HTTP/3 yet, although it is on our roadmap. HTTP/3 is a UDP-based protocol that avoids TCP head-of-line blocking, but it is not widely supported in client libraries yet.

Why HTTP/2 matters here:

  • Multiplexing - you can run many concurrent requests over a single TCP+TLS connection. With HTTP/1.1 you need one connection per concurrent request, and each new connection pays the full TCP + TLS handshake.
  • HPACK header compression - headers like X-Api-Key and long user agents are sent once, then referenced by index. Saves bandwidth on every request.
  • One handshake instead of many - the TLS handshake costs 1-2 round trips. On a 100ms link that's 100-200ms of pure overhead per new connection.

The rule of thumb: one HTTP/2 connection, many streams. Don't open a new connection per request.

Reuse your connections (this is the big one)​

The single most impactful optimization: keep one long-lived HTTP client and reuse it for every request:

Don't do this:

func parallelizedWorker() {
    verisClient := veris.NewClient(apiKey)
    // do some work...
}

func main() {
    for i := 0; i < 100; i++ {
        go parallelizedWorker()
    }
}

Do this instead:

func parallelizedWorker(verisClient *veris.Client) {
    // do some work...
}

func main() {
    verisClient := veris.NewClient(apiKey)

    for i := 0; i < 100; i++ {
        go parallelizedWorker(verisClient)
    }
}

Notice how the first example creates a new client for every request. That means a new TCP connection, a new TLS handshake. The latter example reuses one client across all requests, which is much faster and if you are that kind of person, it also saves some memory and CPU.

Content-Type: always application/json​

Every request body and every response body is JSON. On POST endpoints, always send:

Content-Type: application/json
curl -X POST https://api.verislabs.io/akamai-web/v3/sensor \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session": "...", ...}'

You don't need an Accept header - responses are always JSON, served as application/json.

Timeouts​

Our gateway enforces a hard 10 second limit per request. If your request doesn't complete in 10s, you get a 504 Gateway Timeout.

Recommendations:

  • Set your client timeout slightly above 10s (e.g. 15s). If you set it lower, your client aborts first and you never learn whether the request was actually slow or dead.
  • Normal responses are <10ms for generation endpoints, plus your network latency to us. If you're seeing seconds, something is wrong.

Retries and errors​

Errors always have the same shape:

{"error": "descriptive message"}

You are only charged for 2xx responses - retrying a failed request never costs you double. See Errors and billing for every billing-related error and when to retry.

Concurrency​

There is no global rate limit. Parallelize as much as your workload needs - over a single HTTP/2 connection this is essentially free.

The one exception: on Akamai Web V3, sensor requests on the same session must be spaced at least 1 second apart (physical consistency - a real browser can't generate two sensor payloads in the same millisecond). Different sessions can run fully in parallel.

Debugging: use the request ID​

Every response carries an X-Request-Id header:

X-Request-Id: 5cb7ca8a-fe4b-4422-bd38-1ecbeb5de790

When something looks off, grab this ID and include it when you contact us on Discord. It lets us find your exact request in our logs in seconds instead of minutes.

Checklist​

  • Use HTTP/2 - one connection, many streams
  • Reuse one long-lived HTTP client across all requests
  • Content-Type: application/json on every POST
  • Client timeout ~15s, expect 504 past 10s
  • Log X-Request-Id for support