Error Codes

Every error Gurdx can return, with its code, type and meaning, and how to handle them in your code.

The error envelope#

Errors are delivered with HTTP status 200 and a body in this shape:

{
  "status": "error",
  "code": 101,
  "type": "invalid_key",
  "description": "The API Key is missing or invalid."
}

Codes 101 to 127 are the core set. Codes 128 to 132 are later additions.

All codes#

Handling errors#

Because the HTTP status is 200 for errors too, check status in the body.

PHP#

$res = Http::withToken(env('GURDX_KEY'))->get('https://gurdx.cretip.com/api/lookup/ip', ['ip' => $ip])->json();

if (($res['status'] ?? null) === 'error') {
    match ($res['code']) {
        106 => usleep(500_000),            // slow down, retry later
        103, 105, 127 => notifyBilling(),  // quota or subscription
        101, 113 => alertOps($res),        // key or host problem
        default => logger()->warning('Gurdx error', $res),
    };
    return fallbackDecision();
}

$data = $res['data'];

JavaScript#

const res = await fetch("https://gurdx.cretip.com/api/lookup/ip?ip=1.1.1.1", {
  headers: { Authorization: "Bearer " + process.env.GURDX_KEY },
}).then((r) => r.json());

if (res.status === "error") {
  if (res.code === 106) await new Promise((r) => setTimeout(r, 500));
  throw new Error(`Gurdx ${res.code} ${res.type}: ${res.description}`);
}
console.log(res.data);

Python#

import requests

res = requests.get(
    "https://gurdx.cretip.com/api/lookup/ip",
    params={"ip": "1.1.1.1"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=5,
).json()

if res.get("status") == "error":
    raise RuntimeError(f"Gurdx {res['code']} {res['type']}: {res['description']}")
data = res["data"]

Which errors to retry#

Tip: Log code and type together with the endpoint you called. It makes incidents far easier to diagnose.

Format and errors#

Errors respect the format option when it is valid, so an XML client receives an XML error. If the format itself is invalid (108) or conflicts with callback (109), the error is returned as JSON.